feat!: bump @gusto/embedded-api to v2026-06-15

[jeffredodd]

Summary

Stacked on top of #2255 (upgrade/api-2026-02-01). Upgrades the SDK from @gusto/embedded-api-v-2026-02-01 to @gusto/embedded-api-v-2026-06-15.

Produced autonomously by the api-version-upgrade skill (#2243). v2026-02-01 → v2026-06-15 was eval #3 in that skill's validation suite; this is the first real-world run.

Every breaking change in v2026-06-15 is either:

• handled by existing client-side defenses (Zod schemas, typecheck) — verified by the typecheck CI step
• a server-side serialization format change (number → string-formatted decimal) caught at the call site by tsc and fixed in place with Number() wraps
• a mechanical rename of internal type aliases — verified by tsc --noEmit passing clean
• on an endpoint with no SDK consumer — typecheck is the contract

Breaking changes & how this PR verifies them

Legend: 🔴 = SDK code change required · ⚠️ = verify-only / test fixture update · ✅ = no impact

Status	Change	Where verified
🔴	EmployeeCompensations.grossPay/netPay/checkAmount: number | null → string | null (server now returns string-formatted decimals like "1234.56")	Fixed in src/components/Payroll/PayrollOverview/PayrollOverviewPresentation.tsx (4 sites — wrap reads with Number()); fixtures regenerated in PayrollOverview.stories.tsx, PayrollEditEmployee.stories.tsx, PayrollConfiguration.stories.tsx, and matching .test.tsx. Existing e2e/tests/payroll/91-regular-submit.spec.ts exercises PayrollOverview end-to-end as part of the regular flow — receipt-total assertion would fail if grossPay/netPay rendered as NaN. Typecheck CI.
🔴	models/components/payroll removed → moved to models/components/payrollshow (same exports: Payroll, PayrollPrepared, OffCycleReasonType, EmployeeCompensations)	Import-path sweep in 7 SDK files (helpers.ts, usePreparedPayrollData.ts, payrollTypes.ts, PayrollConfiguration/*, PayrollEditEmployee/*, PayrollHistory/*, PayrollList/*, PayrollOverview/*, helpers.test.ts). Typecheck CI.
🔴	ContractorOnboardingStatus1 → OnboardingStatus (in models/components/contractor)	Fixed: src/shared/constants.ts aliases both the contractor's and employee's OnboardingStatus (same name, two different sources) as ContractorApiOnboardingStatus / EmployeeApiOnboardingStatus. src/components/Common/OnboardingStatusBadge/index.tsx re-aliased to use the per-domain types. Typecheck CI.
🔴	WageType → ContractorWageType (in models/components/contractor)	Fixed in src/components/Contractor/Profile/useContractorProfile.ts: WageType as ApiWageType → ContractorWageType as ApiWageType. Typecheck CI.
🔴	ContractorPayments removed from postv1companiescompanyidcontractorpaymentgroups → renamed to PostV1CompaniesCompanyIdContractorPaymentGroupsContractorPayments	Fixed via import alias in CreatePayment.tsx, CreatePaymentPresentation.tsx, CreatePaymentPresentation.stories.tsx. Typecheck CI + existing e2e/tests/contractor/93-payment-submit.spec.ts.
🔴	PayrollEmployeeCompensationsTypeFixedCompensations → FixedCompensations (and …Hourly… → HourlyCompensations, …Reimbursements → Reimbursements)	Renamed in helpers.ts, helpers.test.ts, PayrollEditEmployeePresentation.tsx, sdk-app/.../PayrollEditEmployeeConfigurations.tsx. Typecheck CI.
🔴	Include removed from getv1companiescompanyidemployees → renamed to GetV1CompaniesCompanyIdEmployeesQueryParamInclude	Aliased in useSelectEmployeesData.ts. Typecheck CI + existing e2e/tests/time-off/04-policy-add-employees-edge-cases.spec.ts.
🔴	SortOrder removed from getv1companiescompanyidpayrolls → renamed to QueryParamSortOrder	Aliased in PayrollHistory.tsx. Typecheck CI.
🔴	PutV1ContractorsContractorIdPaymentMethodType removed → renamed to Type	Aliased in src/test/mocks/apis/contractor_payment_method.ts. Typecheck CI.
🔴	TaxRequirementStatesList.setupComplete removed (legacy field; setupStatus is the replacement and existed in v2026-02-01)	Fixed in src/components/Company/StateTaxes/StateTaxesList/List.tsx: getSetupStatus now returns req.setupStatus ?? SetupStatus.InProgress, dropping the unreachable setupComplete fallback branch. Typecheck CI.
✅	Many nested types inside models/components/* renamed (e.g. BenefitSummaryEmployees → Employees, ContractorPaymentReceiptLicensee → Licensee, EmployeeOnboardingDocumentsConfig → OnboardingDocumentsConfig, etc. — 30+ component files affected)	Typecheck CI — no consumer in src/ imports these nested aliases directly; only top-level types (Employee, Contractor, Payroll, BenefitSummary, …) are imported.
✅	UnprocessableEntityError removed from companiesAcceptTermsOfService / companiesRetrieveTermsOfService / 4× contractor rehire+termination mutation error unions	Typecheck CI — the UnprocessableEntityError class itself still exists; SDK consumers use err instanceof UnprocessableEntityError for runtime narrowing, which still works against the broader error type.
✅	PayrollPayrollStatusMetaType.initialCheckDate / payrollLate widened to nullable	Truthiness checks at PayrollConfiguration.tsx:409-410 handle null correctly. No code change required.
✅	PeopleBatch.PartialSuccess enum value re-added (had been removed in v2026-02-01)	Typecheck CI — additive, no consumer narrows on this value.
✅	versionheader.d.ts re-added in models/components/ (had been removed in v2026-02-01); some react-query hooks now import VersionHeader instead of per-op HeaderXGustoAPIVersion aliases	Typecheck CI — no consumer in src/ imports VersionHeader directly.
✅	Various operation files have new exports added (e.g. Options, SubmissionBlockers on contractor payment group ops; Splits/SplitBy on employee payment method)	Typecheck CI — additive.

What's in this PR

• package.json + package-lock.json: dep swap (@gusto/embedded-api-v-2026-02-01 → @gusto/embedded-api-v-2026-06-15@^0.0.1).
• ~290 src/ files: import-path rename (covers source, tests, MSW mocks under src/test/mocks/apis/, hand-written cache-key string literals).
• ~67 sdk-app/ files: import-path rename + cache-key flips.
• Docs + instruction files (AGENTS.md, CLAUDE.md, src/CLAUDE.md, docs/hooks/*.md, docs/reference/*.md, docs/appendix/jobs-and-compensations.md, build/deriveEndpointInventory.ts, e2e/utils/validationErrorCollector.test.ts): version string updates.
• 🔴 The bare-date X-Gusto-API-Version constant flipped from '2026-02-01' → '2026-06-15' in src/contexts/ApiProvider/apiVersionHook.ts:3, plus matching assertions in apiVersionHook.test.ts (3 sites) and ApiProvider.test.tsx (1 site). Without this flip the upgrade would be a runtime no-op.
• Real fixes:
  • src/components/Payroll/PayrollOverview/PayrollOverviewPresentation.tsx: 4 sites wrapping grossPay/netPay reads with Number() to handle the new string serialization.
  • src/components/Company/StateTaxes/StateTaxesList/List.tsx: simplified getSetupStatus to drop the setupComplete fallback (field removed).
  • Mock data in 6 stories/test files: integers like 880 rewritten as '880' for grossPay/netPay/checkAmount.
  • src/shared/constants.ts + OnboardingStatusBadge/index.tsx: alias the two distinct OnboardingStatus types (contractor vs employee API) by domain.
  • 7 import aliases for renamed nested types.

Deprecations to flag to partners

None new in this version (the v2026-02-01 deprecations of companiesAcceptTermsOfService / companiesRetrieveTermsOfService carry forward unchanged).

Test plan

• CI green on this branch (unit + e2e + typecheck + lint + build)
• No remaining @gusto/embedded-api-v-2026-02-01 refs outside CHANGELOG.md / .reports/ (verified locally; grep returns empty)
• Cache-namespace flip verified end-to-end (mutation under new prefix invalidates queries under new prefix)
• X-Gusto-API-Version HTTP header sends 2026-06-15 on every request (verified by apiVersionHook.test.ts and ApiProvider.test.tsx)
• e2e/tests/payroll/91-regular-submit.spec.ts green — exercises PayrollOverview with the new string-typed grossPay/netPay; receipt total would fail to render if the Number() wraps were missing.

Acknowledgements

Stacked on top of #2255. After #2255 merges, this PR's base should be retargeted to main.

🤖 Generated with Claude Code