refactor(mutations): unify error handling to throw errors from promise-based mutations (#708)

gabrielseco · web-flow · commit 03694dff13da · 2026-01-20T09:19:27.000+01:00
* add mutations

* fix mutation error handling

* fix tests

* fix types

* fix format

* fix handling errors

* refactor(contractor-onboarding): extract error handling logic to shared utility function

* adapt select country

* format
diff --git a/src/flows/ContractorOnboarding/components/BasicInformationStep.tsx b/src/flows/ContractorOnboarding/components/BasicInformationStep.tsx
@@ -1,12 +1,10 @@
 import { BasicInformationFormPayload } from '@/src/flows/Onboarding/types';
 import { EmploymentCreationResponse } from '@/src/client';
 import { $TSFixMe } from '@/src/types/remoteFlows';
-import {
-  normalizeFieldErrors,
-  NormalizedFieldError,
-} from '@/src/lib/mutations';
+import { NormalizedFieldError } from '@/src/lib/mutations';
 import { useContractorOnboardingContext } from '@/src/flows/ContractorOnboarding/context';
 import { ContractorOnboardingForm } from '@/src/flows/ContractorOnboarding/components/ContractorOnboardingForm';
+import { handleStepError } from '@/src/lib/utils';
 
 type BasicInformationStepProps = {
   /*
@@ -49,24 +47,12 @@ export function BasicInformationStep({
         contractorOnboardingBag?.next();
         return;
       }
-      if (response?.error) {
-        const normalizedFieldErrors = normalizeFieldErrors(
-          response?.fieldErrors || [],
-          contractorOnboardingBag.meta?.fields?.basic_information,
-        );
-
-        onError?.({
-          error: response?.error,
-          rawError: response?.rawError,
-          fieldErrors: normalizedFieldErrors,
-        });
-      }
     } catch (error: unknown) {
-      onError?.({
-        error: error as Error,
-        rawError: error as Record<string, unknown>,
-        fieldErrors: [],
-      });
+      const structuredError = handleStepError(
+        error,
+        contractorOnboardingBag.meta?.fields?.basic_information,
+      );
+      onError?.(structuredError);
     }
   };
 
diff --git a/src/flows/ContractorOnboarding/components/ContractDetailsStep.tsx b/src/flows/ContractorOnboarding/components/ContractDetailsStep.tsx
@@ -1,8 +1,5 @@
 import { $TSFixMe } from '@/src/types/remoteFlows';
-import {
-  normalizeFieldErrors,
-  NormalizedFieldError,
-} from '@/src/lib/mutations';
+import { NormalizedFieldError } from '@/src/lib/mutations';
 import { useContractorOnboardingContext } from '@/src/flows/ContractorOnboarding/context';
 import { ContractorOnboardingForm } from '@/src/flows/ContractorOnboarding/components/ContractorOnboardingForm';
 import {
@@ -11,6 +8,7 @@ import {
 } from '@/src/flows/ContractorOnboarding/types';
 import { StatementOfWorkDisclaimer } from '@/src/flows/ContractorOnboarding/components/StatementOfWorkDisclaimer';
 import { isCMOrCMPlus } from '@/src/flows/ContractorOnboarding/utils';
+import { handleStepError } from '@/src/lib/utils';
 
 type ContractDetailsStepProps = {
   /*
@@ -57,24 +55,12 @@ export function ContractDetailsStep({
         contractorOnboardingBag?.next();
         return;
       }
-      if (response?.error) {
-        const normalizedFieldErrors = normalizeFieldErrors(
-          response?.fieldErrors || [],
-          contractorOnboardingBag.meta?.fields?.contract_details,
-        );
-
-        onError?.({
-          error: response?.error,
-          rawError: response?.rawError,
-          fieldErrors: normalizedFieldErrors,
-        });
-      }
     } catch (error: unknown) {
-      onError?.({
-        error: error as Error,
-        rawError: error as Record<string, unknown>,
-        fieldErrors: [],
-      });
+      const structuredError = handleStepError(
+        error,
+        contractorOnboardingBag.meta?.fields?.contract_details,
+      );
+      onError?.(structuredError);
     }
   };
 
diff --git a/src/flows/ContractorOnboarding/components/ContractPreviewStep.tsx b/src/flows/ContractorOnboarding/components/ContractPreviewStep.tsx
@@ -1,14 +1,12 @@
 import { useContractorOnboardingContext } from '@/src/flows/ContractorOnboarding/context';
 import { ContractorOnboardingForm } from '@/src/flows/ContractorOnboarding/components/ContractorOnboardingForm';
-import {
-  NormalizedFieldError,
-  normalizeFieldErrors,
-} from '@/src/lib/mutations';
+import { NormalizedFieldError } from '@/src/lib/mutations';
 import { $TSFixMe } from '@/src/types/remoteFlows';
 import {
   ContractPreviewFormPayload,
   ContractPreviewResponse,
 } from '@/src/flows/ContractorOnboarding/types';
+import { handleStepError } from '@/src/lib/utils';
 
 type ContractPreviewStepProps = {
   /*
@@ -51,24 +49,12 @@ export function ContractPreviewStep({
         contractorOnboardingBag?.next();
         return;
       }
-      if (response?.error) {
-        const normalizedFieldErrors = normalizeFieldErrors(
-          response?.fieldErrors || [],
-          contractorOnboardingBag.meta?.fields?.contract_preview,
-        );
-
-        onError?.({
-          error: response?.error,
-          rawError: response?.rawError,
-          fieldErrors: normalizedFieldErrors,
-        });
-      }
     } catch (error: unknown) {
-      onError?.({
-        error: error as Error,
-        rawError: error as Record<string, unknown>,
-        fieldErrors: [],
-      });
+      const structuredError = handleStepError(
+        error,
+        contractorOnboardingBag.meta?.fields?.contract_preview,
+      );
+      onError?.(structuredError);
     }
   };
 
diff --git a/src/flows/ContractorOnboarding/components/PricingPlan.tsx b/src/flows/ContractorOnboarding/components/PricingPlan.tsx
@@ -1,14 +1,12 @@
 import { $TSFixMe, Components } from '@/src/types/remoteFlows';
-import {
-  normalizeFieldErrors,
-  NormalizedFieldError,
-} from '@/src/lib/mutations';
+import { NormalizedFieldError } from '@/src/lib/mutations';
 import { useContractorOnboardingContext } from '@/src/flows/ContractorOnboarding/context';
 import { ContractorOnboardingForm } from '@/src/flows/ContractorOnboarding/components/ContractorOnboardingForm';
 import {
   PricingPlanFormPayload,
   PricingPlanResponse,
 } from '@/src/flows/ContractorOnboarding/types';
+import { handleStepError } from '@/src/lib/utils';
 
 type PricingPlanStepProps = {
   /**
@@ -56,24 +54,12 @@ export function PricingPlanStep({
         contractorOnboardingBag?.next();
         return;
       }
-      if (response?.error) {
-        const normalizedFieldErrors = normalizeFieldErrors(
-          response?.fieldErrors || [],
-          contractorOnboardingBag.meta?.fields?.pricing_plan,
-        );
-
-        onError?.({
-          error: response?.error,
-          rawError: response?.rawError,
-          fieldErrors: normalizedFieldErrors,
-        });
-      }
     } catch (error: unknown) {
-      onError?.({
-        error: error as Error,
-        rawError: error as Record<string, unknown>,
-        fieldErrors: [],
-      });
+      const structuredError = handleStepError(
+        error,
+        contractorOnboardingBag.meta?.fields?.pricing_plan,
+      );
+      onError?.(structuredError);
     }
   };
 
diff --git a/src/flows/ContractorOnboarding/components/SelectCountryStep.tsx b/src/flows/ContractorOnboarding/components/SelectCountryStep.tsx
@@ -7,6 +7,7 @@ import { NormalizedFieldError } from '@/src/lib/mutations';
 import { $TSFixMe } from '@/src/types/remoteFlows';
 import { useContractorOnboardingContext } from '@/src/flows/ContractorOnboarding/context';
 import { ContractorOnboardingForm } from '@/src/flows/ContractorOnboarding/components/ContractorOnboardingForm';
+import { handleStepError } from '@/src/lib/utils';
 
 type SelectCountryStepProps = {
   /*
@@ -46,19 +47,13 @@ export function SelectCountryStep({
         contractorOnboardingBag?.next();
         return;
       }
-      if (response?.error) {
-        onError?.({
-          error: response.error,
-          rawError: response.rawError,
-          fieldErrors: [],
-        });
-      }
     } catch (error: unknown) {
-      onError?.({
-        error: error as Error,
-        rawError: error as Record<string, unknown>,
-        fieldErrors: [],
-      });
+      const structuredError = handleStepError(
+        error,
+        contractorOnboardingBag.meta?.fields?.select_country,
+      );
+
+      onError?.(structuredError);
     }
   };
 
diff --git a/src/flows/ContractorOnboarding/hooks.tsx b/src/flows/ContractorOnboarding/hooks.tsx
@@ -41,8 +41,8 @@ import {
 import { FlowOptions, JSFModify, JSONSchemaFormType } from '@/src/flows/types';
 import { Step, useStepState } from '@/src/flows/useStepState';
 import { mutationToPromise } from '@/src/lib/mutations';
-import { prettifyFormValues } from '@/src/lib/utils';
-import { $TSFixMe, JSFFieldset, Meta } from '@/src/types/remoteFlows';
+import { createStructuredError, prettifyFormValues } from '@/src/lib/utils';
+import { JSFFieldset, Meta } from '@/src/types/remoteFlows';
 import {
   contractorStandardProductIdentifier,
   contractorPlusProductIdentifier,
@@ -152,25 +152,22 @@ export const useContractorOnboarding = ({
   );
   const createContractorContractDocumentMutation =
     useCreateContractorContractDocument();
-  const { mutateAsync: updateEmploymentMutationAsync } = mutationToPromise(
-    updateEmploymentMutation,
-  );
+  const { mutateAsyncOrThrow: updateEmploymentMutationAsync } =
+    mutationToPromise(updateEmploymentMutation);
   const signContractDocumentMutation = useSignContractDocument();
   const manageContractorSubscriptionMutation =
     usePostManageContractorSubscriptions();
 
-  const { mutateAsync: createEmploymentMutationAsync } = mutationToPromise(
-    createEmploymentMutation,
-  );
+  const { mutateAsyncOrThrow: createEmploymentMutationAsync } =
+    mutationToPromise(createEmploymentMutation);
 
-  const { mutateAsync: createContractorContractDocumentMutationAsync } =
+  const { mutateAsyncOrThrow: createContractorContractDocumentMutationAsync } =
     mutationToPromise(createContractorContractDocumentMutation);
 
-  const { mutateAsync: signContractDocumentMutationAsync } = mutationToPromise(
-    signContractDocumentMutation,
-  );
+  const { mutateAsyncOrThrow: signContractDocumentMutationAsync } =
+    mutationToPromise(signContractDocumentMutation);
 
-  const { mutateAsync: manageContractorSubscriptionMutationAsync } =
+  const { mutateAsyncOrThrow: manageContractorSubscriptionMutationAsync } =
     mutationToPromise(manageContractorSubscriptionMutation);
 
   // if the employment is loaded, country code has not been set yet
@@ -666,17 +663,10 @@ export const useContractorOnboarding = ({
             country_code: internalCountryCode,
             external_id: externalId,
           };
-          try {
-            const response = await createEmploymentMutationAsync(payload);
-            // @ts-expect-error the types from the response are not matching
-            const employmentId = response.data?.data?.employment?.id;
-            setInternalEmploymentId(employmentId);
-
-            return response;
-          } catch (error) {
-            console.error('Error creating onboarding:', error);
-            throw error;
-          }
+          const response = await createEmploymentMutationAsync(payload);
+          const employmentId = response?.data?.employment?.id;
+          setInternalEmploymentId(employmentId);
+          return response;
         } else if (internalEmploymentId) {
           return updateEmploymentMutationAsync({
             employmentId: internalEmploymentId,
@@ -690,13 +680,14 @@ export const useContractorOnboarding = ({
         const payload: CreateContractDocument = {
           contract_document: parsedValues,
         };
-        const response: $TSFixMe =
-          await createContractorContractDocumentMutationAsync({
-            employmentId: internalEmploymentId as string,
-            payload,
-          });
-
-        const contractDocumentId = response.data?.data?.contract_document?.id;
+        const response = await createContractorContractDocumentMutationAsync({
+          employmentId: internalEmploymentId as string,
+          payload,
+        });
+        const contractDocumentId = response?.data?.contract_document?.id;
+        if (!contractDocumentId) {
+          throw createStructuredError('Contract document ID not found');
+        }
         setInternalContractDocumentId(contractDocumentId);
         return response;
       }
@@ -726,11 +717,11 @@ export const useContractorOnboarding = ({
             },
           });
         }
-        return Promise.reject({ error: 'invalid selection' });
+        throw createStructuredError('invalid selection');
       }
 
       default: {
-        throw new Error('Invalid step state');
+        throw createStructuredError('Invalid step state');
       }
     }
   }
@@ -896,7 +887,9 @@ export const useContractorOnboarding = ({
     isSubmitting:
       createEmploymentMutation.isPending ||
       createContractorContractDocumentMutation.isPending ||
-      signContractDocumentMutation.isPending,
+      signContractDocumentMutation.isPending ||
+      manageContractorSubscriptionMutation.isPending ||
+      updateEmploymentMutation.isPending,
 
     /**
      * Document preview PDF data
diff --git a/src/flows/ContractorOnboarding/tests/ContractorOnboarding.test.tsx b/src/flows/ContractorOnboarding/tests/ContractorOnboarding.test.tsx
@@ -552,13 +552,13 @@ describe('ContractorOnboardingFlow', () => {
     });
   });
 
-  it('should NOT call PATCH when resubmitting basic information (contractors cannot be updated)', async () => {
+  it('should call PATCH when resubmitting basic information', async () => {
     const patchSpy = vi.fn();
 
     server.use(
       http.patch('*/v1/employments/*', () => {
         patchSpy();
-        return HttpResponse.json({});
+        return HttpResponse.json(employmentUpdatedResponse);
       }),
     );
 
@@ -609,10 +609,11 @@ describe('ContractorOnboardingFlow', () => {
     const nextButton = screen.getByText(/Next Step/i);
     nextButton.click();
 
-    await screen.findByText(/Step: Pricing Plan/i);
+    await waitFor(() => {
+      expect(patchSpy).toHaveBeenCalledTimes(1);
+    });
 
-    // Verify PATCH was NOT called (contractors can't be updated)
-    expect(patchSpy).toHaveBeenCalled();
+    await screen.findByText(/Step: Pricing Plan/i);
   });
 
   it('should create contract document when submitting contract details', async () => {
diff --git a/src/flows/ContractorOnboarding/tests/fixtures.ts b/src/flows/ContractorOnboarding/tests/fixtures.ts
@@ -3693,6 +3693,10 @@ export const mockManageSubscriptionResponse = {
   },
 };
 
-export const mockContractDocumentSignedResponse = {};
+export const mockContractDocumentSignedResponse = {
+  data: {
+    status: 'ok',
+  },
+};
 
 export const inviteResponse = {};
diff --git a/src/lib/__tests__/mutations.test.ts b/src/lib/__tests__/mutations.test.ts
diff --git a/src/lib/mutations.ts b/src/lib/mutations.ts
diff --git a/src/lib/utils.ts b/src/lib/utils.ts
