feat(contractor-onboarding) - support skippable errors (#787)

gabrielseco · web-flow · commit e2870589c872 · 2026-03-11T13:22:48.000+01:00
* feat(contractor-onboarding) - support skippable errors

* add feedback

* format

* fix warning

* fix review eligibility

* add test

* add tests

* add test

* tests

* fix css

* fix resubmission

* simplify

* fix types
diff --git a/example/src/ContractorOnboarding.tsx b/example/src/ContractorOnboarding.tsx
@@ -225,10 +225,37 @@ const MultiStepForm = ({
               response: ContractorOnboardingContractDetailsResponse,
             ) => console.log('response', response)}
             onError={({ error, fieldErrors }) => {
+              console.log('error', error);
               setErrors({ apiError: error.message, fieldErrors });
             }}
           />
           <AlertError errors={errors} />
+          {contractorOnboardingBag.canSkipAiValidation && (
+            <div className='bg-yellow-50 border-l-4 border-yellow-400 p-4 mb-4'>
+              <div className='flex'>
+                <div className='flex-shrink-0'>
+                  <svg
+                    className='h-5 w-5 text-yellow-400'
+                    viewBox='0 0 20 20'
+                    fill='currentColor'
+                  >
+                    <path
+                      fillRule='evenodd'
+                      d='M8.257 3.099c.765-1.36 2.722-1.36 3.486 0l5.58 9.92c.75 1.334-.213 2.98-1.742 2.98H4.42c-1.53 0-2.493-1.646-1.743-2.98l5.58-9.92zM11 13a1 1 0 11-2 0 1 1 0 012 0zm-1-8a1 1 0 00-1 1v3a1 1 0 002 0V6a1 1 0 00-1-1z'
+                      clipRule='evenodd'
+                    />
+                  </svg>
+                </div>
+                <div className='ml-3'>
+                  <p className='text-sm text-yellow-700'>
+                    AI validation detected potential compliance issues. You can
+                    edit the Services and Deliverables field above or continue
+                    at your own risk by clicking Submit again.
+                  </p>
+                </div>
+              </div>
+            </div>
+          )}
           <div className='contractor-onboarding-buttons-container'>
             <BackButton
               className='back-button'
@@ -240,7 +267,9 @@ const MultiStepForm = ({
               className='submit-button'
               onClick={() => setErrors({ apiError: '', fieldErrors: [] })}
             >
-              Continue
+              {contractorOnboardingBag.canSkipAiValidation
+                ? 'Continue Anyway'
+                : 'Continue'}
             </SubmitButton>
           </div>
         </div>
diff --git a/example/src/ReviewContractorOnboardingStep.tsx b/example/src/ReviewContractorOnboardingStep.tsx
@@ -90,20 +90,22 @@ export const ReviewContractorOnboardingStep = ({
         Edit Pricing Plan
       </button>
       {onboardingBag.stepState.values?.pricing_plan?.subscription ===
-        corProductIdentifier && (
-        <>
-          <h2 className='title'>Eligibility Questionnaire</h2>
-          <ReviewMeta
-            meta={onboardingBag.meta.fields.eligibility_questionnaire}
-          />
-          <button
-            className='back-button'
-            onClick={() => onboardingBag.goTo('eligibility_questionnaire')}
-          >
-            Edit Eligibility Questionnaire
-          </button>
-        </>
-      )}
+        corProductIdentifier &&
+        Object.keys(onboardingBag.meta.fields.eligibility_questionnaire)
+          .length > 0 && (
+          <>
+            <h2 className='title'>Eligibility Questionnaire</h2>
+            <ReviewMeta
+              meta={onboardingBag.meta.fields.eligibility_questionnaire}
+            />
+            <button
+              className='back-button'
+              onClick={() => onboardingBag.goTo('eligibility_questionnaire')}
+            >
+              Edit Eligibility Questionnaire
+            </button>
+          </>
+        )}
       <h2 className='title'>Contract Details</h2>
       <ReviewMeta meta={onboardingBag.meta.fields.contract_details} />
       <button
diff --git a/example/src/css/contractor-onboarding.css b/example/src/css/contractor-onboarding.css
@@ -75,6 +75,6 @@
   flex-direction: column;
   gap: 16px;
   flex-direction: column-reverse;
-  max-width: 95px;
+  max-width: 140px;
   margin: 0 auto;
 }
diff --git a/src/flows/ContractorOnboarding/constants.ts b/src/flows/ContractorOnboarding/constants.ts
@@ -18,6 +18,14 @@ export const PRODUCT_IDENTIFIER_MAP: Record<ProductType, string> = {
 
 export const IR35_FILE_SUBTYPE = 'ir_35';
 
+export const REMOTE_AI_ERROR_SOURCE = 'REMOTE_AI';
+
+export const REMOTE_AI_SERVICES_AND_DELIVERABLES_ERROR_MESSAGE =
+  "You cannot control how a contractor completes the Services and Deliverables. This means, for example, that you can't specify their working hours or use of subcontractors. Please make sure this field includes only project names, descriptions, and deliverables. We do not allow hyperlinks.";
+
+export const REMOTE_AI_SERVICES_AND_DELIVERABLES_COR_ERROR_MESSAGE =
+  'The content You have entered may not be consistent with the Contractor of Record terms. You are responsible before proceeding for ensuring that the language entered herein accurately reflects those terms and your relationship with Subcontractors.';
+
 const standardOnboardingWorkflow = [
   {
     title: 'You add a new contractor and their details in Remote.',
diff --git a/src/flows/ContractorOnboarding/hooks.tsx b/src/flows/ContractorOnboarding/hooks.tsx
@@ -53,12 +53,15 @@ import {
   contractorPlusProductIdentifier,
   corProductIdentifier,
   eorProductIdentifier,
+  REMOTE_AI_ERROR_SOURCE,
 } from '@/src/flows/ContractorOnboarding/constants';
 import {
   buildBasicInformationJsfModify,
   buildContractDetailsJsfModify,
   buildContractPreviewJsfModify,
 } from '@/src/flows/ContractorOnboarding/jsfModify';
+import { transformAiErrorResponse } from '@/src/flows/ContractorOnboarding/utils';
+import { AiValidationError } from '@/src/flows/ContractorOnboarding/types';
 import { useUploadFile } from '@/src/common/api/files';
 import { dataURLtoFile } from '@/src/lib/files';
 import { useEmploymentQuery } from '@/src/common/api/employment';
@@ -544,6 +547,7 @@ export const useContractorOnboarding = ({
         descriptionProvisionalStartDate,
         selectedPricingPlan,
         fieldValues,
+        selectedPricingPlan === corProductIdentifier,
       ),
     },
   });
@@ -902,6 +906,25 @@ export const useContractorOnboarding = ({
     return {};
   };
 
+  /**
+   * Extracts AI validation error from the error response
+   * @param error - The error object from the API call
+   * @returns The AI validation error if found, null otherwise
+   */
+  const extractAiValidationError = (
+    error: $TSFixMe,
+  ): AiValidationError | null => {
+    const errorData = error?.rawError?.error?.errors?.services_and_deliverables;
+    if (errorData?.source === REMOTE_AI_ERROR_SOURCE) {
+      return {
+        error: errorData.error,
+        source: errorData.source,
+        skippable: errorData.skippable,
+      };
+    }
+    return null;
+  };
+
   async function onSubmit(values: FieldValues) {
     const currentStepName = stepState.currentStep.name;
     if (currentStepName in fieldsMetaRef.current) {
@@ -974,20 +997,41 @@ export const useContractorOnboarding = ({
         return;
       }
       case 'contract_details': {
+        console.log('parsedValues', parsedValues);
+        const shouldSkipAiChecks =
+          fieldValues.services_and_deliverables_error_skippable === true;
         const payload: CreateContractDocument = {
           contract_document: parsedValues,
+          skip_ai_checks: shouldSkipAiChecks,
         };
-        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;
+        try {
+          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;
+        } catch (error) {
+          const aiError = extractAiValidationError(error);
+          if (aiError) {
+            const isContractorOfRecord =
+              selectedPricingPlan === corProductIdentifier;
+            setFieldValues({
+              ...values,
+              services_and_deliverables_ai_warning:
+                transformAiErrorResponse(isContractorOfRecord),
+              services_and_deliverables_error_skippable: aiError.skippable,
+            });
+          }
+
+          throw error;
+        }
       }
 
       case 'contract_preview': {
@@ -1199,6 +1243,14 @@ export const useContractorOnboarding = ({
      */
     parseFormValues,
 
+    /**
+     * Indicates whether AI validation errors can be skipped (user can continue at their own risk).
+     * True when there's a skippable AI validation error on services_and_deliverables field.
+     * @returns {boolean}
+     */
+    canSkipAiValidation:
+      fieldValues.services_and_deliverables_error_skippable === true,
+
     /**
      * Function to validate form values against the onboarding schema
      * @param values - Form values to validate
diff --git a/src/flows/ContractorOnboarding/jsfModify.tsx b/src/flows/ContractorOnboarding/jsfModify.tsx
@@ -1,16 +1,25 @@
+import { format } from 'date-fns';
+import { FieldValues } from 'react-hook-form';
+import { ChangeEvent } from 'react';
+
 import { createStatementProperty } from '@/src/components/form/jsf-utils/createFields';
 import { zendeskArticles } from '@/src/components/shared/zendesk-drawer/utils';
 import { ZendeskTriggerButton } from '@/src/components/shared/zendesk-drawer/ZendeskTriggerButton';
 import { ContractPreviewHeader } from '@/src/flows/ContractorOnboarding/components/ContractPreviewHeader';
 import { ContractPreviewStatement } from '@/src/flows/ContractorOnboarding/components/ContractPreviewStatement';
-import { contractorStandardProductIdentifier } from '@/src/flows/ContractorOnboarding/constants';
-import { ContractorOnboardingFlowProps } from '@/src/flows/ContractorOnboarding/types';
+import {
+  contractorStandardProductIdentifier,
+  REMOTE_AI_SERVICES_AND_DELIVERABLES_COR_ERROR_MESSAGE,
+  REMOTE_AI_SERVICES_AND_DELIVERABLES_ERROR_MESSAGE,
+} from '@/src/flows/ContractorOnboarding/constants';
+import {
+  ContractorOnboardingFlowProps,
+  ContractorOnboardingContractDetailsFormPayload,
+} from '@/src/flows/ContractorOnboarding/types';
 import { isNationalityCountryCode } from '@/src/flows/ContractorOnboarding/utils';
 import { JSFModify } from '@/src/flows/types';
 import { FILE_TYPES, MAX_FILE_SIZE } from '@/src/lib/uploadConfig';
 import { JSFCustomComponentProps } from '@/src/types/remoteFlows';
-import { format } from 'date-fns';
-import { FieldValues } from 'react-hook-form';
 
 const isStandardPricingPlan = (pricingPlan: string | undefined) => {
   return pricingPlan === contractorStandardProductIdentifier;
@@ -36,6 +45,31 @@ const showBackDateWarning = (
   return undefined;
 };
 
+/**
+ * Handles changes to the services_and_deliverables field to clear AI warning state
+ */
+function onServicesAndDeliverablesChange(
+  _event: ChangeEvent<HTMLTextAreaElement>,
+  values: ContractorOnboardingContractDetailsFormPayload & {
+    services_and_deliverables_ai_warning: string;
+    services_and_deliverables_error_skippable: boolean;
+  },
+  setValues: (
+    formValues: Partial<
+      ContractorOnboardingContractDetailsFormPayload & {
+        services_and_deliverables_ai_warning: string;
+        services_and_deliverables_error_skippable: boolean;
+      }
+    >,
+  ) => void,
+) {
+  setValues({
+    ...values,
+    services_and_deliverables_ai_warning: '',
+    services_and_deliverables_error_skippable: false,
+  });
+}
+
 /**
  * Merges internal jsfModify modifications with user-provided options for contract_details step
  * This abstracts the logic of applying internal field modifications (like dynamic descriptions)
@@ -46,6 +80,7 @@ export const buildContractDetailsJsfModify = (
   provisionalStartDateDescription: string | undefined,
   selectedPricingPlan: string | undefined,
   fieldValues: FieldValues,
+  isContractorOfRecord: boolean,
 ): JSFModify => {
   const isStandardPricingPlanSelected =
     isStandardPricingPlan(selectedPricingPlan);
@@ -55,8 +90,30 @@ export const buildContractDetailsJsfModify = (
     isStandardPricingPlanSelected,
     provisionalStartDate,
   );
+  const AiStatementWarning = createStatementProperty({
+    severity: 'warning',
+    title: 'Possible misclassification risk',
+    description: isContractorOfRecord
+      ? REMOTE_AI_SERVICES_AND_DELIVERABLES_COR_ERROR_MESSAGE
+      : REMOTE_AI_SERVICES_AND_DELIVERABLES_ERROR_MESSAGE,
+  });
   return {
     ...userJsfModify,
+    create: {
+      ...userJsfModify?.create,
+      services_and_deliverables_ai_warning: {
+        type: 'string',
+        'x-jsf-presentation': {
+          inputType: 'hidden',
+        },
+      },
+      services_and_deliverables_error_skippable: {
+        type: 'boolean',
+        'x-jsf-presentation': {
+          inputType: 'hidden',
+        },
+      },
+    },
     fields: {
       ...userJsfModify?.fields,
       ...{
@@ -69,6 +126,16 @@ export const buildContractDetailsJsfModify = (
             ...statement,
           },
         },
+        services_and_deliverables: {
+          onChange: onServicesAndDeliverablesChange,
+          'x-jsf-presentation': {
+            calculateDynamicProperties: (formValues: FieldValues) => ({
+              statement: formValues.services_and_deliverables_ai_warning
+                ? AiStatementWarning.statement
+                : undefined,
+            }),
+          },
+        },
       },
     },
   };
diff --git a/src/flows/ContractorOnboarding/tests/ContractorOnboarding.test.tsx b/src/flows/ContractorOnboarding/tests/ContractorOnboarding.test.tsx
diff --git a/src/flows/ContractorOnboarding/types.ts b/src/flows/ContractorOnboarding/types.ts
diff --git a/src/flows/ContractorOnboarding/utils.ts b/src/flows/ContractorOnboarding/utils.ts

Original file line number	Diff line number	Diff line change
`@@ -75,6 +75,6 @@`
`75`	`75`	`flex-direction: column;`
`76`	`76`	`gap: 16px;`
`77`	`77`	`flex-direction: column-reverse;`
`78`		`- max-width: 95px;`
	`78`	`+ max-width: 140px;`
`79`	`79`	`margin: 0 auto;`
`80`	`80`	`}`