Add validation for invalid field API names in getFirstValue

README.md

@@ -36,8 +36,8 @@ If the record collection is null, empty, or the field value is null, the respons
 ## Behavior Notes
 
 - The first record is determined by the **existing collection order**
-- No sorting or validation of the field API name is performed
-- If the field does not exist or the value is null, the response is `null`
+- If the provided `fieldApiName` does not exist on the SObject, an `IllegalArgumentException` is thrown with a descriptive message
+- If the field value is null, the response is `null`
 - All returned values are converted to **String**
 
 ---

force-app/main/default/classes/CollectionGetFirstValue_Records.cls

@@ -14,6 +14,16 @@ public with sharing class CollectionGetFirstValue_Records {
             }
 
             SObject firstRecord = req.records[0];
+
+            Schema.SObjectType sObjectType = firstRecord.getSObjectType();
+            Map<String, Schema.SObjectField> fieldMap = sObjectType.getDescribe().fields.getMap();
+
+            if (!fieldMap.containsKey(req.fieldApiName.toLowerCase())) {
+                throw new IllegalArgumentException(
+                    'Invalid field API name \'' + req.fieldApiName + '\' for SObject type \'' + sObjectType.getDescribe().getName() + '\'.'
+                );
+            }
+
             Object fieldValue = firstRecord.get(req.fieldApiName);
 
             resp.response = (fieldValue == null) ? null : String.valueOf(fieldValue);

force-app/main/default/classes/CollectionGetFirstValue_RecordsTest.cls

@@ -35,6 +35,27 @@ public with sharing class CollectionGetFirstValue_RecordsTest {
         System.assertEquals(String.valueOf(aInserted.Id), responses[2].response, 'Id should be returned as string for inserted record');
     }
 
+    @IsTest
+    static void testGetFirstValue_InvalidFieldApiName() {
+        Account a = new Account(Name = 'Test Account');
+
+        CollectionGetFirstValue_Records.Request req = new CollectionGetFirstValue_Records.Request();
+        req.records = new List<SObject>{ a };
+        req.fieldApiName = 'NonExistentField__xyz';
+
+        List<CollectionGetFirstValue_Records.Request> requests = new List<CollectionGetFirstValue_Records.Request>{ req };
+
+        try {
+            CollectionGetFirstValue_Records.getFirstValue(requests);
+            System.assert(false, 'Expected IllegalArgumentException was not thrown for invalid field API name');
+        } catch (IllegalArgumentException e) {
+            System.assert(e.getMessage().contains('NonExistentField__xyz'), 'Exception message should contain the invalid field name');
+            System.assert(e.getMessage().contains('Account'), 'Exception message should contain the SObject type name');
+        } catch (Exception e) {
+            System.assert(false, 'Unexpected exception type thrown: ' + e.getTypeName() + ' - ' + e.getMessage());
+        }
+    }
+
     @IsTest
     static void testGetFirstValue_NullRecordsField() {
         CollectionGetFirstValue_Records.Request req = new CollectionGetFirstValue_Records.Request();