fix(contractor-onboarding) - handle not nested errors

[gabrielseco]

Problem

Users were reporting a bug in the sandbox as the response structure wasn't the same one that we'll receive in partners env

When doing a POST v1/contractors/employments/ae8556c6-5f18-405c-b789-f10f9b9372e7/contract-documents against partners

{ "error": { "errors": { "services_and_deliverables": { "error": [ "The text is non-compliant because it mentions 'weekly progress reviews' which implies a level of day-to-day supervision or control over the contractor's work, similar to performance reviews used for employees." ], "source": "REMOTE_AI", "skippable": true } } } }

In theory on the sandbox env for them is when the error happens but I haven't been able to reproduce the exact same thing, I got returned the same as partners but this is what they were getting

{ "errors": { "services_and_deliverables": { "error": [ "The text is non-compliant because it includes language that implies weekly progress reviews, which can be interpreted as a form of day-to-day supervision or control over the Contractor's work." ], "source": "REMOTE_AI", "skippable": true } } }

Solution

After giving two rounds of thinking, the way is normalize the errors so I always get returned the same thing

Second part is adding a type guard to get types and avoid reaching rawError

I added docs to cursor + bugbot

Note

Medium Risk
Changes the shape/typing of errors thrown by mutationToPromise().mutateAsyncOrThrow, which can affect downstream catch blocks and onboarding flow behavior. Coverage is improved with new unit/integration tests, but error handling is a cross-cutting concern.

Overview
Fixes mutation error handling by introducing a standardized MutationErrorStructure plus an isMutationError() type guard, and by enriching mutateAsyncOrThrow rejections with normalizedErrors (from either nested error.error.errors or flat error.errors) and an optional response.

Updates Contractor Onboarding’s AI-validation parsing to use the type guard and normalizedErrors (replacing unsafe rawError digging), and adds/updates tests to cover production-style 422 payloads and the new error shape expectations.

Adds Cursor review guidance enforcing the new type-safe error-handling pattern via documentation and an always-on editor rule.

^{Reviewed by Cursor Bugbot for commit a17978f. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

📦 Bundle Size Report

Metric	Current	Previous	Change	Status
Total (gzip)	211.58 kB	211.37 kB	+210 B (+0.1%)	🔴
Total (raw)	572.93 kB	572.65 kB	+274 B (+0.0%)	🔴
CSS (gzip)	20.86 kB	20.86 kB	0 B (0%)	🟢
CSS (raw)	108.83 kB	108.83 kB	0 B (0%)	🟢

Size Limits

• ✅ Total gzipped: 211.58 kB / 250 kB (84.6%)
• ✅ Total raw: 572.93 kB / 600 kB (95.5%)
• ✅ CSS gzipped: 20.86 kB / 25 kB (83.4%)

Largest Files (Top 5)

1. chunk-5BU3CD2P.js - 14 kB (new)
2. styles.css - 10.43 kB (0 B (0%))
3. index.css - 10.43 kB (0 B (0%))
4. index.js - 6.1 kB (+11 B (+0.2%))
5. chunk-TNQKP2XT.js - 5.89 kB (0 B (0%))

View All Files (312 total)

File	Size (gzip)	Change
chunk-5BU3CD2P.js	14 kB	new
styles.css	10.43 kB	0 B (0%)
index.css	10.43 kB	0 B (0%)
index.js	6.1 kB	+11 B (+0.2%)
chunk-TNQKP2XT.js	5.89 kB	0 B (0%)
chunk-7AQ7V57P.js	5.81 kB	new
chunk-JXAAON7I.js	5.26 kB	new
chunk-J4NCN3TG.js	4.62 kB	new
chunk-24IYN4NB.js	4.38 kB	new
chunk-72K4C6OR.js	4.06 kB	new

✅ Bundle size check passed

[github-actions]

📊 Coverage Report

⚠️ Coverage decreased

Metric	Current	Previous	Change	Status
Lines	89.99%	90.03%	-0.04%	🔴
Statements	89.66%	89.70%	-0.04%	🔴
Functions	87.70%	87.69%	+0.01%	🟢
Branches	80.02%	80.06%	-0.04%	🔴

Detailed Breakdown

Lines Coverage

• Covered: 3677 / 4086
• Coverage: 89.99%
• Change: -0.04% (2 lines)

Statements Coverage

• Covered: 3738 / 4169
• Coverage: 89.66%
• Change: -0.04% (2 statements)

Functions Coverage

• Covered: 998 / 1138
• Coverage: 87.70%
• Change: +0.01% (1 functions)

Branches Coverage

• Covered: 2283 / 2853
• Coverage: 80.02%
• Change: -0.04% (11 branches)

✅ Coverage check passed

[github-actions]

Deploy preview for remote-flows ready!

Project:	remote-flows
Status:	✅  Deploy successful!
Preview URL:	https://remote-flows-5v8qttl11-remotecom.vercel.app
Latest Commit:	a17978f
Inspect:	View deployment

Deployed with vercel-action