@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/building-sf-integrations/assets/callouts/http-response-handler.cls

@@ -0,0 +1,257 @@
+/**
+ * @description HTTP Response Handler Utility
+ *
+ * Use Case: Standardized response parsing and error handling
+ * - Parse JSON responses to typed objects
+ * - Handle different content types
+ * - Extract error messages from various API formats
+ * - Logging for debugging
+ *
+ * @author {{Author}}
+ * @date {{Date}}
+ */
+public with sharing class HttpResponseHandler {
+
+    /**
+     * @description Parse HTTP response to Map
+     * @param response HttpResponse to parse
+     * @return Parsed response as Map<String, Object>
+     * @throws HttpResponseException for error status codes
+     */
+    public static Map<String, Object> parseJsonResponse(HttpResponse response) {
+        validateSuccessResponse(response);
+
+        String body = response.getBody();
+        if (String.isBlank(body) || response.getStatusCode() == 204) {
+            return new Map<String, Object>();
+        }
+
+        try {
+            return (Map<String, Object>) JSON.deserializeUntyped(body);
+        } catch (JSONException e) {
+            throw new HttpResponseException(
+                'Failed to parse JSON response: ' + e.getMessage() +
+                '. Body: ' + body.left(500)
+            );
+        }
+    }
+
+    /**
+     * @description Parse HTTP response to List
+     * @param response HttpResponse to parse
+     * @return Parsed response as List<Object>
+     * @throws HttpResponseException for error status codes
+     */
+    public static List<Object> parseJsonArrayResponse(HttpResponse response) {
+        validateSuccessResponse(response);
+
+        String body = response.getBody();
+        if (String.isBlank(body)) {
+            return new List<Object>();
+        }
+
+        try {
+            return (List<Object>) JSON.deserializeUntyped(body);
+        } catch (JSONException e) {
+            throw new HttpResponseException(
+                'Failed to parse JSON array response: ' + e.getMessage()
+            );
+        }
+    }
+
+    /**
+     * @description Parse HTTP response to specific type
+     * @param response HttpResponse to parse
+     * @param targetType Apex type to deserialize to
+     * @return Deserialized object
+     * @throws HttpResponseException for error status codes
+     */
+    public static Object parseTypedResponse(HttpResponse response, Type targetType) {
+        validateSuccessResponse(response);
+
+        String body = response.getBody();
+        if (String.isBlank(body)) {
+            return null;
+        }
+
+        try {
+            return JSON.deserialize(body, targetType);
+        } catch (JSONException e) {
+            throw new HttpResponseException(
+                'Failed to deserialize response to ' + targetType.getName() + ': ' + e.getMessage()
+            );
+        }
+    }
+
+    /**
+     * @description Validate response is successful (2xx)
+     * @param response HttpResponse to validate
+     * @throws HttpResponseException for non-2xx status codes
+     */
+    public static void validateSuccessResponse(HttpResponse response) {
+        Integer statusCode = response.getStatusCode();
+
+        // Log response for debugging
+        logResponse(response);
+
+        if (statusCode >= 200 && statusCode < 300) {
+            return; // Success
+        }
+
+        String errorMessage = extractErrorMessage(response);
+
+        if (statusCode >= 400 && statusCode < 500) {
+            throw new ClientErrorException(
+                'HTTP ' + statusCode + ': ' + errorMessage
+            );
+        }
+
+        if (statusCode >= 500) {
+            throw new ServerErrorException(
+                'HTTP ' + statusCode + ': ' + errorMessage
+            );
+        }
+
+        throw new HttpResponseException(
+            'Unexpected HTTP status ' + statusCode + ': ' + errorMessage
+        );
+    }
+
+    /**
+     * @description Extract error message from response body
+     * @param response HttpResponse containing error
+     * @return Error message string
+     */
+    public static String extractErrorMessage(HttpResponse response) {
+        String body = response.getBody();
+
+        if (String.isBlank(body)) {
+            return 'No response body';
+        }
+
+        // Try to parse as JSON error
+        try {
+            Map<String, Object> errorObj = (Map<String, Object>) JSON.deserializeUntyped(body);
+
+            // Common error formats
+            // Format 1: { "error": "message" }
+            if (errorObj.containsKey('error')) {
+                Object error = errorObj.get('error');
+                if (error instanceof String) {
+                    return (String) error;
+                }
+                if (error instanceof Map<String, Object>) {
+                    Map<String, Object> errorMap = (Map<String, Object>) error;
+                    if (errorMap.containsKey('message')) {
+                        return (String) errorMap.get('message');
+                    }
+                }
+            }
+
+            // Format 2: { "message": "error message" }
+            if (errorObj.containsKey('message')) {
+                return (String) errorObj.get('message');
+            }
+
+            // Format 3: { "errors": [{ "message": "..." }] }
+            if (errorObj.containsKey('errors')) {
+                Object errors = errorObj.get('errors');
+                if (errors instanceof List<Object>) {
+                    List<Object> errorList = (List<Object>) errors;
+                    if (!errorList.isEmpty()) {
+                        Object firstError = errorList[0];
+                        if (firstError instanceof Map<String, Object>) {
+                            Map<String, Object> errMap = (Map<String, Object>) firstError;
+                            if (errMap.containsKey('message')) {
+                                return (String) errMap.get('message');
+                            }
+                        }
+                        if (firstError instanceof String) {
+                            return (String) firstError;
+                        }
+                    }
+                }
+            }
+
+            // Format 4: { "detail": "error detail" }
+            if (errorObj.containsKey('detail')) {
+                return (String) errorObj.get('detail');
+            }
+
+            // Fallback: return serialized error object
+            return JSON.serialize(errorObj);
+
+        } catch (Exception e) {
+            // Not JSON - return raw body (truncated)
+            return body.left(1000);
+        }
+    }
+
+    /**
+     * @description Log HTTP response for debugging
+     * @param response HttpResponse to log
+     */
+    private static void logResponse(HttpResponse response) {
+        System.debug(LoggingLevel.DEBUG, '=== HTTP Response ===');
+        System.debug(LoggingLevel.DEBUG, 'Status: ' + response.getStatusCode() + ' ' + response.getStatus());
+
+        // Log important headers
+        String[] headerKeys = new String[]{ 'Content-Type', 'X-Request-Id', 'Retry-After', 'X-RateLimit-Remaining' };
+        for (String key : headerKeys) {
+            String value = response.getHeader(key);
+            if (String.isNotBlank(value)) {
+                System.debug(LoggingLevel.DEBUG, key + ': ' + value);
+            }
+        }
+
+        // Log body (truncated for large responses)
+        String body = response.getBody();
+        if (String.isNotBlank(body)) {
+            System.debug(LoggingLevel.DEBUG, 'Body: ' + body.left(5000));
+        }
+    }
+
+    /**
+     * @description Get response header value
+     * @param response HttpResponse
+     * @param headerName Header name to retrieve
+     * @return Header value or null
+     */
+    public static String getHeader(HttpResponse response, String headerName) {
+        return response.getHeader(headerName);
+    }
+
+    /**
+     * @description Check if response indicates success
+     * @param response HttpResponse to check
+     * @return True if status code is 2xx
+     */
+    public static Boolean isSuccess(HttpResponse response) {
+        Integer statusCode = response.getStatusCode();
+        return statusCode >= 200 && statusCode < 300;
+    }
+
+    /**
+     * @description Check if response indicates rate limiting
+     * @param response HttpResponse to check
+     * @return True if status code is 429
+     */
+    public static Boolean isRateLimited(HttpResponse response) {
+        return response.getStatusCode() == 429;
+    }
+
+    /**
+     * @description Base exception for HTTP response errors
+     */
+    public virtual class HttpResponseException extends Exception {}
+
+    /**
+     * @description Exception for 4xx client errors
+     */
+    public class ClientErrorException extends HttpResponseException {}
+
+    /**
+     * @description Exception for 5xx server errors
+     */
+    public class ServerErrorException extends HttpResponseException {}
+}

package/skills/building-sf-integrations/assets/callouts/rest-queueable-callout.cls

@@ -0,0 +1,262 @@
+/**
+ * @description Asynchronous REST Callout using Queueable
+ *
+ * Use Case: Callouts triggered from DML operations
+ * - Trigger-based integrations
+ * - Process Builder / Flow callouts
+ * - Any callout after DML (insert, update, delete)
+ *
+ * CRITICAL: Synchronous callouts are NOT allowed after DML.
+ *           Always use Queueable with Database.AllowsCallouts for such scenarios.
+ *
+ * Features:
+ * - Implements Database.AllowsCallouts for HTTP requests
+ * - Processes records in batches
+ * - Includes error handling and logging
+ * - Supports job chaining for pagination
+ *
+ * @author {{Author}}
+ * @date {{Date}}
+ */
+public with sharing class {{ServiceName}}QueueableCallout implements Queueable, Database.AllowsCallouts {
+
+    private static final String NAMED_CREDENTIAL = 'callout:{{NamedCredentialName}}';
+    private static final Integer DEFAULT_TIMEOUT = 120000;
+    private static final Integer BATCH_SIZE = 10; // Callouts per job (max 100 per transaction)
+
+    private List<Id> recordIds;
+    private String operation;
+    private Integer startIndex;
+
+    /**
+     * @description Constructor for processing records
+     * @param recordIds List of record IDs to process
+     * @param operation Operation type (CREATE, UPDATE, DELETE, SYNC)
+     */
+    public {{ServiceName}}QueueableCallout(List<Id> recordIds, String operation) {
+        this(recordIds, operation, 0);
+    }
+
+    /**
+     * @description Constructor with pagination support
+     * @param recordIds List of record IDs to process
+     * @param operation Operation type
+     * @param startIndex Starting index for batch processing
+     */
+    public {{ServiceName}}QueueableCallout(List<Id> recordIds, String operation, Integer startIndex) {
+        this.recordIds = recordIds;
+        this.operation = operation;
+        this.startIndex = startIndex;
+    }
+
+    /**
+     * @description Execute the queueable job
+     * @param context QueueableContext
+     */
+    public void execute(QueueableContext context) {
+        if (recordIds == null || recordIds.isEmpty()) {
+            return;
+        }
+
+        // Calculate batch bounds
+        Integer endIndex = Math.min(startIndex + BATCH_SIZE, recordIds.size());
+        List<Id> batchIds = new List<Id>();
+        for (Integer i = startIndex; i < endIndex; i++) {
+            batchIds.add(recordIds[i]);
+        }
+
+        try {
+            // Query records for this batch
+            List<{{ObjectName}}> records = [
+                SELECT Id, Name{{AdditionalFields}}
+                FROM {{ObjectName}}
+                WHERE Id IN :batchIds
+                WITH USER_MODE
+            ];
+
+            // Process each record
+            List<{{ObjectName}}> toUpdate = new List<{{ObjectName}}>();
+            for ({{ObjectName}} record : records) {
+                try {
+                    processRecord(record, operation);
+                    // Mark success on record if needed
+                    record.Integration_Status__c = 'Success';
+                    record.Integration_Date__c = Datetime.now();
+                    toUpdate.add(record);
+                } catch (Exception e) {
+                    // Log individual record failure
+                    System.debug(LoggingLevel.ERROR,
+                        'Failed to process record ' + record.Id + ': ' + e.getMessage());
+                    record.Integration_Status__c = 'Error';
+                    record.Integration_Error__c = e.getMessage().left(255);
+                    toUpdate.add(record);
+                }
+            }
+
+            // Update records with sync status
+            if (!toUpdate.isEmpty()) {
+                update toUpdate;
+            }
+
+            // Chain next batch if more records remain
+            if (endIndex < recordIds.size()) {
+                System.enqueueJob(
+                    new {{ServiceName}}QueueableCallout(recordIds, operation, endIndex)
+                );
+            }
+
+        } catch (Exception e) {
+            System.debug(LoggingLevel.ERROR, '{{ServiceName}}QueueableCallout Error: ' + e.getMessage());
+            System.debug(LoggingLevel.ERROR, 'Stack Trace: ' + e.getStackTraceString());
+            // Consider: Create Integration_Log__c record, send notification, etc.
+        }
+    }
+
+    /**
+     * @description Process a single record with external API
+     * @param record The record to process
+     * @param operation The operation type
+     */
+    private void processRecord({{ObjectName}} record, String operation) {
+        switch on operation {
+            when 'CREATE' {
+                createExternalRecord(record);
+            }
+            when 'UPDATE' {
+                updateExternalRecord(record);
+            }
+            when 'DELETE' {
+                deleteExternalRecord(record.Id);
+            }
+            when 'SYNC' {
+                syncExternalRecord(record);
+            }
+            when else {
+                throw new IntegrationException('Unknown operation: ' + operation);
+            }
+        }
+    }
+
+    /**
+     * @description Create record in external system
+     * @param record Salesforce record
+     */
+    private void createExternalRecord({{ObjectName}} record) {
+        Map<String, Object> payload = buildPayload(record);
+
+        HttpRequest req = new HttpRequest();
+        req.setEndpoint(NAMED_CREDENTIAL + '/{{Endpoint}}');
+        req.setMethod('POST');
+        req.setHeader('Content-Type', 'application/json');
+        req.setTimeout(DEFAULT_TIMEOUT);
+        req.setBody(JSON.serialize(payload));
+
+        HttpResponse res = new Http().send(req);
+        handleResponse(res, record.Id);
+    }
+
+    /**
+     * @description Update record in external system
+     * @param record Salesforce record
+     */
+    private void updateExternalRecord({{ObjectName}} record) {
+        if (String.isBlank(record.External_Id__c)) {
+            throw new IntegrationException('No external ID for record: ' + record.Id);
+        }
+
+        Map<String, Object> payload = buildPayload(record);
+
+        HttpRequest req = new HttpRequest();
+        req.setEndpoint(NAMED_CREDENTIAL + '/{{Endpoint}}/' + record.External_Id__c);
+        req.setMethod('PUT');
+        req.setHeader('Content-Type', 'application/json');
+        req.setTimeout(DEFAULT_TIMEOUT);
+        req.setBody(JSON.serialize(payload));
+
+        HttpResponse res = new Http().send(req);
+        handleResponse(res, record.Id);
+    }
+
+    /**
+     * @description Delete record from external system
+     * @param recordId Salesforce record ID
+     */
+    private void deleteExternalRecord(Id recordId) {
+        // Query for external ID
+        {{ObjectName}} record = [
+            SELECT External_Id__c
+            FROM {{ObjectName}}
+            WHERE Id = :recordId
+            WITH USER_MODE
+            LIMIT 1
+        ];
+
+        if (String.isBlank(record.External_Id__c)) {
+            return; // Nothing to delete externally
+        }
+
+        HttpRequest req = new HttpRequest();
+        req.setEndpoint(NAMED_CREDENTIAL + '/{{Endpoint}}/' + record.External_Id__c);
+        req.setMethod('DELETE');
+        req.setTimeout(DEFAULT_TIMEOUT);
+
+        HttpResponse res = new Http().send(req);
+        handleResponse(res, recordId);
+    }
+
+    /**
+     * @description Sync record with external system (get latest and update)
+     * @param record Salesforce record
+     */
+    private void syncExternalRecord({{ObjectName}} record) {
+        if (String.isBlank(record.External_Id__c)) {
+            createExternalRecord(record);
+        } else {
+            updateExternalRecord(record);
+        }
+    }
+
+    /**
+     * @description Build API payload from Salesforce record
+     * @param record Salesforce record
+     * @return Payload map for API
+     */
+    private Map<String, Object> buildPayload({{ObjectName}} record) {
+        return new Map<String, Object>{
+            'salesforceId' => record.Id,
+            'name' => record.Name
+            // Add more field mappings as needed
+        };
+    }
+
+    /**
+     * @description Handle HTTP response
+     * @param res HTTP response
+     * @param recordId Salesforce record ID (for logging)
+     */
+    private void handleResponse(HttpResponse res, Id recordId) {
+        Integer statusCode = res.getStatusCode();
+
+        if (statusCode >= 200 && statusCode < 300) {
+            System.debug(LoggingLevel.DEBUG, 'Success for ' + recordId + ': ' + res.getBody());
+            return;
+        }
+
+        if (statusCode >= 400 && statusCode < 500) {
+            throw new IntegrationException(
+                'Client Error (' + statusCode + ') for ' + recordId + ': ' + res.getBody()
+            );
+        }
+
+        if (statusCode >= 500) {
+            throw new IntegrationException(
+                'Server Error (' + statusCode + ') for ' + recordId + ': ' + res.getBody()
+            );
+        }
+    }
+
+    /**
+     * @description Custom exception for integration errors
+     */
+    public class IntegrationException extends Exception {}
+}