feat!: bump @gusto/embedded-api to v2026-02-01 [skill-driven competing PR]

[jeffredodd]

This is a competing PR generated autonomously by the api-version-upgrade skill for comparison against the hand-built PR #2233. Same source/target API versions, same upgrade goal — different author. Use this PR as the skill's reference output; reviewers can diff the two PRs to validate the skill produces a sound upgrade end-to-end.

Summary

Upgrade the SDK from @gusto/embedded-api-v-2025-11-15 to @gusto/embedded-api-v-2026-02-01.

Every breaking change in v2026-02-01 is either:

• handled by an in-place mechanical fix (usePreparedPayrollData.ts) — typecheck verifies
• a bare-date runtime constant flip (apiVersionHook.ts) — unit tests verify
• a string/literal sweep across 13 sites — grep -rln "@gusto/embedded-api-v-2025-11-15" . returns empty
• on an endpoint with no SDK consumer — typecheck CI is the contract

Breaking-change matrix

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

Status	Change	SDK consumer	Verification
🔴	QueryParamSortBy removed from putv1companiescompanyidpayrollspayrollidprepare; sortBy collapses to string	src/components/Payroll/usePreparedPayrollData.ts:6,15	Import removed; sortBy?: string. Typecheck CI.
🔴	Bare-date X-Gusto-API-Version runtime constant ('2025-11-15' → '2026-02-01')	src/contexts/ApiProvider/apiVersionHook.ts:3 (+ 2 test files)	Bare-date sed sweep. Unit assertions in apiVersionHook.test.ts + ApiProvider.test.tsx.
⚠️	Cache-namespace string literals '@gusto/embedded-api-v-2025-11-15' flipped at 13+ sites	createSdkQueryClient.ts, ApiProvider.tsx, TimeOff/*, Company/Locations/*, sdk-app/.../contractor-management/*	Single sed sweep. grep -rln "@gusto/embedded-api-v-2025-11-15" . --exclude-dir=node_modules --exclude=package-lock.json --exclude=CHANGELOG.md → empty.
✅	PartnerManagedCompanyMigrateRequest collapses to {} (signer resolved from authed admin)	None (grep partnerManagedCompanies|MigrateRequest src/ sdk-app/ empty)	Typecheck CI
✅	MigrationStatus renamed → PartnerManagedCompanyMigrateResponseErrorsCategory; new Errors/Warnings on migrate response	None	Typecheck CI
✅	Errors/Warnings namespaced on migration_readiness response	None	Typecheck CI
✅	Company.fundingType: Brex removed; PartnerDisbursement, Rtp, LineOfCredit added	No 'brex' narrowing in src/	Typecheck CI
✅	EmployeeBenefit.deductionReducesTaxableIncome: required → optional (widening)	n/a (widening is safe)	Typecheck CI
✅	PayrollCreditBlockerUnblockOptionWaitForReverseWireMetadata collapses to {}	No reverseWireDetailId consumer	Typecheck CI
✅	ContractorPayment* adds optional invoiceNumber, memo	Additive	Typecheck CI
✅	GetV1CompanyFormsQueryParamSortBy removed; SortBy removed from getv1...payrollid (collapse to string)	No consumer of either (payrolls.ts mock imports Request/Response types, not SortBy)	Typecheck CI
✅	PostV1CompaniesCompanyIdReportsEmployeesAnnualFicaWageResponseBody removed (uses shared EmployeesAnnualFicaWageReportAcceptance component now)	No consumer	Typecheck CI
✅	peoplebatch.PartialSuccess enum value removed	No 'partial_success' consumer	Typecheck CI
✅	New endpoints: partnerManagedCompanies*TermsOfService, payrollDigests* + PayrollDigestConflictError	Additive	n/a
✅	payroll.autoPilot doc rename → "automatic payroll enabled" (field name unchanged)	n/a (doc-only)	Typecheck CI
✅	getinformationrequests adds optional sortBy query param	Additive	Typecheck CI
✅	Mutation error unions widened (NotFoundErrorObject / UnprocessableEntityError added to many ops)	Widening is safe	Typecheck CI
✅	VersionHeader component removed; per-op HeaderXGustoAPIVersion enum constants added	SDK doesn't import VersionHeader	Typecheck CI

What's in this PR

• package.json + package-lock.json: @gusto/embedded-api-v-2025-11-15@^0.0.2 → @gusto/embedded-api-v-2026-02-01@^0.0.1.
• ~360 src/ + sdk-app/ files: import-path rename (single sed sweep).
• 13 sites with hardcoded cache-key literals: namespace flip — same regex.
• src/contexts/ApiProvider/apiVersionHook.ts:3 + 3 test files: bare-date '2025-11-15' → '2026-02-01'. Separate explicit sed; the package-name sweep does not catch this.
• Docs + instruction files: AGENTS.md, CLAUDE.md, src/CLAUDE.md, docs/hooks/, docs/api/, docs/reference/, build/deriveEndpointInventory.ts, e2e/utils/validationErrorCollector.test.ts.
• src/components/Payroll/usePreparedPayrollData.ts: removed QueryParamSortBy import; sortBy?: string.
• Fix pre-existing MD040 lint surfaced by the touch (add language tags to fenced code blocks in AGENTS.md, src/CLAUDE.md).

Bare-date sweep — verification

# Should return only Storybook story-date fixtures (calendar values), never SDK runtime code
$ grep -rn "'2025-11-15'\|\"2025-11-15\"" src/ sdk-app/ e2e/ | grep -v node_modules
src/components/Payroll/PayrollList/PayrollStatusShowcase.stories.tsx:29:    endDate: '2025-11-15',
src/components/Payroll/PayrollList/PayrollStatusShowcase.stories.tsx:54:        endDate: '2025-11-15',
src/components/Payroll/PayrollList/PayrollStatusShowcase.stories.tsx:829:        endDate: '2025-11-15',

These are payroll period-end calendar dates in a Storybook story — unrelated to the API version header.

$ grep -n "CURRENT_API_VERSION" src/contexts/ApiProvider/apiVersionHook.ts
3:const CURRENT_API_VERSION = '2026-02-01'

Deviations from PR #2233 (for reviewers)

This PR is intentionally narrower than PR #2233. Differences a reviewer should know about:

• No E2E specs added. PR feat!: bump @gusto/embedded-api to v2026-02-01 #2233 added two specs (e2e/tests/employee/04-self-onboarding-email-required.spec.ts and e2e/tests/company/03-migration-status-boolean.spec.ts). The first guards a server-side change (email-required on the self-onboarding endpoint at create time) that does not appear in the package's type diff — the SDK's existing Zod schema already requires email when the self-onboarding switch is on, so the type contract is unchanged. The skill's analysis is driven by the type diff, so it did not surface this row. If this server-side behavior change is real, that spec should be ported here too — call this out in review. The migration-status spec is an exploratory anchor for a partner-managed company flow that the SDK has no current consumer for (see PR feat!: bump @gusto/embedded-api to v2026-02-01 #2233's own description acknowledging the misscope); it is verify-only and the skill correctly omits it.
• Single base PR, no sub-PRs. Matches PR feat!: bump @gusto/embedded-api to v2026-02-01 #2233's structure.
• No release-notes coordination beyond this PR body. Mutation-error union widening is non-breaking from the SDK's perspective but partners who narrow on specific error unions in their app code may need a heads-up. Same as PR feat!: bump @gusto/embedded-api to v2026-02-01 #2233.
• No docs/upgrade-notes/ file or migration guide. Same as PR feat!: bump @gusto/embedded-api to v2026-02-01 #2233.

Test plan

• All CI green (unit + typecheck + lint + build)
• E2E suite green against Demo (verifies cache-namespace flip end-to-end: any mutation under the new prefix would fail to invalidate the new-prefixed queries if a literal site were missed)
• DevTools network tab confirms outgoing X-Gusto-API-Version: 2026-02-01 header on a real request
• grep -rln "@gusto/embedded-api-v-2025-11-15" . returns no hits outside CHANGELOG.md / .reports/ / node_modules/
• Side-by-side diff against PR feat!: bump @gusto/embedded-api to v2026-02-01 #2233 reveals no missed breaking change

🤖 Generated with Claude Code via the api-version-upgrade skill

[jeffredodd]

Closing in favor of a fresh skill-driven run using the iteration-4 skill. PR #2244 was generated by the iteration-3 skill which lacked the 'trust the error pipeline' decision rule (added in PR #2243's latest commit). The new run will produce the canonical upgrade PR.