@salesforce/afv-skills 1.22.0 → 1.23.0

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

@@ -1,211 +0,0 @@
-/**
- * @description Synchronous REST Callout Service for {{ServiceName}}
- *
- * Use Case: Real-time API calls where immediate response is needed
- * - User-initiated actions requiring feedback
- * - API calls NOT triggered from DML operations
- *
- * IMPORTANT: Do NOT use synchronous callouts from triggers or DML contexts.
- *            Use rest-queueable-callout.cls template instead.
- *
- * @author {{Author}}
- * @date {{Date}}
- */
-public with sharing class {{ServiceName}}Callout {
-
-    // Named Credential reference (configured in Setup)
-    private static final String NAMED_CREDENTIAL = 'callout:{{NamedCredentialName}}';
-
-    // Default timeout (max 120000 ms = 120 seconds)
-    private static final Integer DEFAULT_TIMEOUT = 120000;
-
-    /**
-     * @description Make HTTP request to external API
-     * @param method HTTP method (GET, POST, PUT, PATCH, DELETE)
-     * @param endpoint API endpoint path (appended to Named Credential base URL)
-     * @param body Request body (null for GET/DELETE)
-     * @return HttpResponse from external API
-     */
-    public static HttpResponse makeRequest(String method, String endpoint, String body) {
-        HttpRequest req = new HttpRequest();
-        req.setEndpoint(NAMED_CREDENTIAL + endpoint);
-        req.setMethod(method);
-        req.setHeader('Content-Type', 'application/json');
-        req.setHeader('Accept', 'application/json');
-        req.setTimeout(DEFAULT_TIMEOUT);
-
-        if (String.isNotBlank(body) && (method == 'POST' || method == 'PUT' || method == 'PATCH')) {
-            req.setBody(body);
-        }
-
-        Http http = new Http();
-        return http.send(req);
-    }
-
-    /**
-     * @description GET request
-     * @param endpoint API endpoint path
-     * @return Parsed response as Map
-     */
-    public static Map<String, Object> get(String endpoint) {
-        HttpResponse res = makeRequest('GET', endpoint, null);
-        return handleResponse(res);
-    }
-
-    /**
-     * @description GET request with query parameters
-     * @param endpoint API endpoint path
-     * @param params Query parameters
-     * @return Parsed response as Map
-     */
-    public static Map<String, Object> get(String endpoint, Map<String, String> params) {
-        String queryString = buildQueryString(params);
-        String fullEndpoint = String.isNotBlank(queryString)
-            ? endpoint + '?' + queryString
-            : endpoint;
-        return get(fullEndpoint);
-    }
-
-    /**
-     * @description POST request
-     * @param endpoint API endpoint path
-     * @param payload Request body as Map
-     * @return Parsed response as Map
-     */
-    public static Map<String, Object> post(String endpoint, Map<String, Object> payload) {
-        HttpResponse res = makeRequest('POST', endpoint, JSON.serialize(payload));
-        return handleResponse(res);
-    }
-
-    /**
-     * @description PUT request (full resource update)
-     * @param endpoint API endpoint path
-     * @param payload Request body as Map
-     * @return Parsed response as Map
-     */
-    public static Map<String, Object> put(String endpoint, Map<String, Object> payload) {
-        HttpResponse res = makeRequest('PUT', endpoint, JSON.serialize(payload));
-        return handleResponse(res);
-    }
-
-    /**
-     * @description PATCH request (partial resource update)
-     * @param endpoint API endpoint path
-     * @param payload Request body as Map
-     * @return Parsed response as Map
-     */
-    public static Map<String, Object> patch(String endpoint, Map<String, Object> payload) {
-        HttpResponse res = makeRequest('PATCH', endpoint, JSON.serialize(payload));
-        return handleResponse(res);
-    }
-
-    /**
-     * @description DELETE request
-     * @param endpoint API endpoint path
-     * @return Parsed response as Map (may be empty for 204)
-     */
-    public static Map<String, Object> del(String endpoint) {
-        HttpResponse res = makeRequest('DELETE', endpoint, null);
-        return handleResponse(res);
-    }
-
-    /**
-     * @description Handle HTTP response and parse JSON
-     * @param res HttpResponse from callout
-     * @return Parsed response as Map
-     * @throws CalloutException for error status codes
-     */
-    private static Map<String, Object> handleResponse(HttpResponse res) {
-        Integer statusCode = res.getStatusCode();
-        String responseBody = res.getBody();
-
-        // Log for debugging (consider removing in production or use custom logging)
-        System.debug(LoggingLevel.DEBUG, 'Response Status: ' + statusCode);
-        System.debug(LoggingLevel.DEBUG, 'Response Body: ' + responseBody);
-
-        // Success (2xx)
-        if (statusCode >= 200 && statusCode < 300) {
-            if (String.isBlank(responseBody) || statusCode == 204) {
-                return new Map<String, Object>();
-            }
-            return (Map<String, Object>) JSON.deserializeUntyped(responseBody);
-        }
-
-        // Client Error (4xx)
-        if (statusCode >= 400 && statusCode < 500) {
-            String errorMessage = parseErrorMessage(responseBody);
-            throw new ClientException('Client Error (' + statusCode + '): ' + errorMessage);
-        }
-
-        // Server Error (5xx)
-        if (statusCode >= 500) {
-            throw new ServerException('Server Error (' + statusCode + '): ' + responseBody);
-        }
-
-        // Unexpected status
-        throw new CalloutException('Unexpected status code: ' + statusCode);
-    }
-
-    /**
-     * @description Parse error message from response body
-     * @param responseBody Raw response body
-     * @return Error message string
-     */
-    private static String parseErrorMessage(String responseBody) {
-        try {
-            Map<String, Object> errorResponse = (Map<String, Object>) JSON.deserializeUntyped(responseBody);
-
-            // Common error message field names
-            if (errorResponse.containsKey('error')) {
-                Object error = errorResponse.get('error');
-                if (error instanceof String) {
-                    return (String) error;
-                } else if (error instanceof Map<String, Object>) {
-                    Map<String, Object> errorObj = (Map<String, Object>) error;
-                    return (String) errorObj.get('message');
-                }
-            }
-            if (errorResponse.containsKey('message')) {
-                return (String) errorResponse.get('message');
-            }
-            if (errorResponse.containsKey('errors')) {
-                return JSON.serialize(errorResponse.get('errors'));
-            }
-
-            return responseBody;
-        } catch (Exception e) {
-            return responseBody;
-        }
-    }
-
-    /**
-     * @description Build URL query string from parameters
-     * @param params Map of query parameters
-     * @return Encoded query string
-     */
-    private static String buildQueryString(Map<String, String> params) {
-        if (params == null || params.isEmpty()) {
-            return '';
-        }
-
-        List<String> pairs = new List<String>();
-        for (String key : params.keySet()) {
-            String value = params.get(key);
-            if (String.isNotBlank(value)) {
-                pairs.add(EncodingUtil.urlEncode(key, 'UTF-8') + '=' +
-                          EncodingUtil.urlEncode(value, 'UTF-8'));
-            }
-        }
-        return String.join(pairs, '&');
-    }
-
-    /**
-     * @description Client error (4xx) exception
-     */
-    public class ClientException extends Exception {}
-
-    /**
-     * @description Server error (5xx) exception
-     */
-    public class ServerException extends Exception {}
-}

package/skills/building-sf-integrations/assets/cdc/cdc-handler.cls

@@ -1,246 +0,0 @@
-/**
- * @description Change Data Capture (CDC) Handler for {{ObjectName}}
- *
- * Use Case: Business logic for processing CDC events
- * - Sync changes to external systems
- * - Maintain audit logs
- * - Trigger downstream processes
- *
- * This class is called by the {{ObjectName}}CDCSubscriber trigger
- * and contains all business logic for CDC event processing.
- *
- * @author {{Author}}
- * @date {{Date}}
- */
-public with sharing class {{ObjectName}}CDCHandler {
-
-    // Fields to watch for sync (ignore changes to other fields)
-    private static final Set<String> SYNC_FIELDS = new Set<String>{
-        'Name',
-        'Status__c',
-        'Amount__c'
-        // Add fields that should trigger sync
-    };
-
-    /**
-     * @description Handle CREATE change events
-     * @param event The CDC event
-     * @param header The change event header
-     */
-    public static void handleCreate({{ObjectName}}ChangeEvent event, EventBus.ChangeEventHeader header) {
-        List<String> recordIds = header.getRecordIds();
-        Datetime commitTime = header.getCommitTimestamp();
-
-        System.debug(LoggingLevel.DEBUG,
-            'CDC CREATE - Records: ' + recordIds + ' at ' + commitTime);
-
-        // Build payload from event field values
-        Map<String, Object> payload = buildPayloadFromEvent(event);
-        payload.put('recordIds', recordIds);
-        payload.put('operation', 'CREATE');
-        payload.put('timestamp', commitTime);
-
-        // Queue sync to external system
-        System.enqueueJob(new ExternalSyncQueueable(payload));
-    }
-
-    /**
-     * @description Handle UPDATE change events
-     * @param event The CDC event
-     * @param header The change event header
-     * @param changedFields List of changed field API names
-     */
-    public static void handleUpdate(
-        {{ObjectName}}ChangeEvent event,
-        EventBus.ChangeEventHeader header,
-        List<String> changedFields
-    ) {
-        List<String> recordIds = header.getRecordIds();
-
-        // Check if any sync-relevant fields changed
-        Boolean relevantChange = false;
-        List<String> relevantFields = new List<String>();
-
-        for (String field : changedFields) {
-            if (SYNC_FIELDS.contains(field)) {
-                relevantChange = true;
-                relevantFields.add(field);
-            }
-        }
-
-        if (!relevantChange) {
-            System.debug(LoggingLevel.DEBUG,
-                'CDC UPDATE - Ignoring (no sync fields changed): ' + changedFields);
-            return;
-        }
-
-        System.debug(LoggingLevel.DEBUG,
-            'CDC UPDATE - Records: ' + recordIds +
-            ', Relevant changed fields: ' + relevantFields);
-
-        // Build payload with changed values
-        Map<String, Object> payload = buildPayloadFromEvent(event);
-        payload.put('recordIds', recordIds);
-        payload.put('operation', 'UPDATE');
-        payload.put('changedFields', relevantFields);
-        payload.put('timestamp', header.getCommitTimestamp());
-
-        // Queue sync to external system
-        System.enqueueJob(new ExternalSyncQueueable(payload));
-    }
-
-    /**
-     * @description Handle DELETE change events
-     * @param recordIds Deleted record IDs
-     * @param header The change event header
-     */
-    public static void handleDelete(List<String> recordIds, EventBus.ChangeEventHeader header) {
-        System.debug(LoggingLevel.DEBUG,
-            'CDC DELETE - Records: ' + recordIds);
-
-        Map<String, Object> payload = new Map<String, Object>{
-            'recordIds' => recordIds,
-            'operation' => 'DELETE',
-            'timestamp' => header.getCommitTimestamp()
-        };
-
-        // Queue delete sync to external system
-        System.enqueueJob(new ExternalSyncQueueable(payload));
-    }
-
-    /**
-     * @description Handle UNDELETE change events
-     * @param event The CDC event
-     * @param header The change event header
-     */
-    public static void handleUndelete({{ObjectName}}ChangeEvent event, EventBus.ChangeEventHeader header) {
-        // Treat undelete like create - sync full record
-        handleCreate(event, header);
-    }
-
-    /**
-     * @description Handle GAP events (missed events)
-     * @param recordIds Affected record IDs
-     * @param gapType Type of gap event
-     */
-    public static void handleGap(List<String> recordIds, String gapType) {
-        System.debug(LoggingLevel.WARN,
-            'CDC GAP - Type: ' + gapType + ', Records: ' + recordIds);
-
-        // Query current state of records and sync
-        // This ensures we have accurate data despite missed events
-        /*
-        List<{{ObjectName}}> records = [
-            SELECT Id, Name, Status__c, Amount__c
-            FROM {{ObjectName}}
-            WHERE Id IN :recordIds
-            WITH USER_MODE
-        ];
-
-        for ({{ObjectName}} record : records) {
-            Map<String, Object> payload = new Map<String, Object>{
-                'recordIds' => new List<String>{record.Id},
-                'operation' => 'SYNC', // Full sync due to gap
-                'data' => record
-            };
-            System.enqueueJob(new ExternalSyncQueueable(payload));
-        }
-        */
-    }
-
-    /**
-     * @description Handle GAP_OVERFLOW (too many changes)
-     * @param entityName The object API name
-     */
-    public static void handleOverflow(String entityName) {
-        System.debug(LoggingLevel.ERROR,
-            'CDC OVERFLOW for ' + entityName + ' - Full sync required!');
-
-        // Create alert/task for admin attention
-        /*
-        Task alertTask = new Task(
-            Subject = 'CDC Overflow - Full Sync Required for ' + entityName,
-            Description = 'Change Data Capture experienced overflow. ' +
-                         'Some events were missed. Full sync is required.',
-            Priority = 'High',
-            Status = 'Open',
-            ActivityDate = Date.today()
-        );
-        insert alertTask;
-        */
-
-        // Consider triggering a batch job for full sync
-        // Database.executeBatch(new FullSyncBatch(entityName));
-    }
-
-    /**
-     * @description Build payload map from CDC event field values
-     * @param event The CDC event
-     * @return Map of field values
-     */
-    private static Map<String, Object> buildPayloadFromEvent({{ObjectName}}ChangeEvent event) {
-        Map<String, Object> payload = new Map<String, Object>();
-
-        // Map event fields to payload
-        // Only non-null values are changed fields
-        payload.put('Name', event.Name);
-        // payload.put('Status__c', event.Status__c);
-        // payload.put('Amount__c', event.Amount__c);
-        // Add more fields as needed
-
-        // Remove null values (unchanged fields)
-        Set<String> keysToRemove = new Set<String>();
-        for (String key : payload.keySet()) {
-            if (payload.get(key) == null) {
-                keysToRemove.add(key);
-            }
-        }
-        for (String key : keysToRemove) {
-            payload.remove(key);
-        }
-
-        return payload;
-    }
-
-    /**
-     * @description Queueable job for syncing to external system
-     */
-    public class ExternalSyncQueueable implements Queueable, Database.AllowsCallouts {
-        private Map<String, Object> payload;
-
-        public ExternalSyncQueueable(Map<String, Object> payload) {
-            this.payload = payload;
-        }
-
-        public void execute(QueueableContext context) {
-            try {
-                // Call external system with payload
-                // Example: Use Named Credential + REST callout
-                /*
-                HttpRequest req = new HttpRequest();
-                req.setEndpoint('callout:ExternalSystem/sync');
-                req.setMethod('POST');
-                req.setHeader('Content-Type', 'application/json');
-                req.setBody(JSON.serialize(payload));
-
-                Http http = new Http();
-                HttpResponse res = http.send(req);
-
-                if (res.getStatusCode() >= 200 && res.getStatusCode() < 300) {
-                    System.debug('Sync successful');
-                } else {
-                    System.debug('Sync failed: ' + res.getStatusCode());
-                }
-                */
-
-                System.debug(LoggingLevel.DEBUG,
-                    'External sync payload: ' + JSON.serialize(payload));
-
-            } catch (Exception e) {
-                System.debug(LoggingLevel.ERROR,
-                    'External sync failed: ' + e.getMessage());
-                // Consider: Create error log, retry logic, DLQ
-            }
-        }
-    }
-}

package/skills/building-sf-integrations/assets/cdc/cdc-subscriber-trigger.trigger

@@ -1,139 +0,0 @@
-/**
- * @description Change Data Capture (CDC) Subscriber Trigger for {{ObjectName}}
- *
- * Use Case: React to data changes in near real-time
- * - Sync data to external systems
- * - Audit logging
- * - Cache invalidation
- * - Event-driven integrations
- *
- * CDC Channel Name: {{ObjectName}}ChangeEvent
- * - Standard objects: AccountChangeEvent, ContactChangeEvent, etc.
- * - Custom objects: MyObject__ChangeEvent (append "ChangeEvent" to API name)
- *
- * Key Concepts:
- * - ChangeEventHeader contains metadata (changeType, changedFields, recordIds)
- * - Event contains changed field values (nulls for unchanged fields)
- * - Supports CREATE, UPDATE, DELETE, UNDELETE change types
- * - Gap events indicate missed events (handle replay)
- *
- * IMPORTANT:
- * - Enable CDC for object in Setup → Integrations → Change Data Capture
- * - Triggers fire in separate transaction from DML
- * - Events are retained for 3 days (replay window)
- *
- * @author {{Author}}
- * @date {{Date}}
- */
-trigger {{ObjectName}}CDCSubscriber on {{ObjectName}}ChangeEvent (after insert) {
-
-    // Track replay ID for checkpoint
-    String lastReplayId = '';
-
-    for ({{ObjectName}}ChangeEvent event : Trigger.new) {
-        // Store replay ID
-        lastReplayId = event.ReplayId;
-
-        // Get change event header (metadata about the change)
-        EventBus.ChangeEventHeader header = event.ChangeEventHeader;
-
-        // Extract header information
-        String changeType = header.getChangeType();
-        List<String> changedFields = header.getChangedFields();
-        List<String> recordIds = header.getRecordIds();
-        String entityName = header.getEntityName();
-        Long commitNumber = header.getCommitNumber();
-        Datetime commitTimestamp = header.getCommitTimestamp();
-        String transactionKey = header.getTransactionKey();
-
-        // Log event details
-        System.debug(LoggingLevel.DEBUG,
-            'CDC Event - Type: ' + changeType +
-            ', Entity: ' + entityName +
-            ', Records: ' + recordIds +
-            ', Changed Fields: ' + changedFields);
-
-        try {
-            // Route based on change type
-            switch on changeType {
-                when 'CREATE' {
-                    {{ObjectName}}CDCHandler.handleCreate(event, header);
-                }
-                when 'UPDATE' {
-                    {{ObjectName}}CDCHandler.handleUpdate(event, header, changedFields);
-                }
-                when 'DELETE' {
-                    {{ObjectName}}CDCHandler.handleDelete(recordIds, header);
-                }
-                when 'UNDELETE' {
-                    {{ObjectName}}CDCHandler.handleUndelete(event, header);
-                }
-                when 'GAP_CREATE', 'GAP_UPDATE', 'GAP_DELETE', 'GAP_UNDELETE' {
-                    // Gap events indicate missed events
-                    // Should trigger full sync for affected records
-                    System.debug(LoggingLevel.WARN,
-                        'GAP event detected - some events may have been missed. ' +
-                        'Type: ' + changeType + ', Records: ' + recordIds);
-                    {{ObjectName}}CDCHandler.handleGap(recordIds, changeType);
-                }
-                when 'GAP_OVERFLOW' {
-                    // Too many changes to track - full sync needed
-                    System.debug(LoggingLevel.ERROR,
-                        'GAP_OVERFLOW - full sync required for ' + entityName);
-                    {{ObjectName}}CDCHandler.handleOverflow(entityName);
-                }
-            }
-
-        } catch (Exception e) {
-            // Log error but continue processing
-            System.debug(LoggingLevel.ERROR,
-                'CDC processing error for ' + recordIds + ': ' + e.getMessage());
-            System.debug(LoggingLevel.ERROR, 'Stack: ' + e.getStackTraceString());
-        }
-    }
-
-    // Set resume checkpoint for durability
-    if (String.isNotBlank(lastReplayId)) {
-        EventBus.TriggerContext.currentContext().setResumeCheckpoint(lastReplayId);
-    }
-}
-
-/*
- * ============================================================================
- * CDC TRIGGER BEST PRACTICES
- * ============================================================================
- *
- * 1. ENABLE CDC FOR OBJECT
- *    Setup → Integrations → Change Data Capture → Select Objects
- *
- * 2. HANDLE ALL CHANGE TYPES
- *    - CREATE: New record
- *    - UPDATE: Record modified
- *    - DELETE: Record deleted
- *    - UNDELETE: Record restored from recycle bin
- *    - GAP_*: Events were missed (sync required)
- *    - GAP_OVERFLOW: Too many changes (full sync needed)
- *
- * 3. USE CHANGEDEVENTHEAD FOR METADATA
- *    - getChangeType(): Operation type
- *    - getChangedFields(): List of changed field API names
- *    - getRecordIds(): Affected record IDs
- *    - getCommitTimestamp(): When change occurred
- *
- * 4. FIELD VALUES IN EVENT
- *    - Changed fields have new values
- *    - Unchanged fields are NULL
- *    - Use changedFields list to know what changed
- *
- * 5. IDEMPOTENT HANDLERS
- *    - Same event might fire multiple times
- *    - Use transactionKey to detect duplicates
- *    - Design handlers to be safe for replay
- *
- * 6. BULK CONSIDERATIONS
- *    - Multiple records can be in single event (batch DML)
- *    - Use getRecordIds() to get all affected IDs
- *    - Process all record IDs efficiently
- *
- * ============================================================================
- */

package/skills/building-sf-integrations/assets/endpoint-security/example.cspTrustedSite-meta.xml

@@ -1,58 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
-    CSP Trusted Site Template
-
-    Use this template when creating integration skills that make HTTP callouts
-    to external APIs.
-
-    RECOMMENDED: This is the MODERN approach (API 48+ / Spring '20+)
-    that replaces Remote Site Settings.
-
-    CSP (Content Security Policy) advantages:
-    - More granular control over security contexts
-    - Better alignment with web security standards
-    - Per-context security (Apex, Lightning, etc.)
-    - Future-proof
-
-    Setup:
-    1. Copy this file to your skill's assets/ directory
-    2. Replace {{placeholders}} with your values
-    3. Deploy to org OR let setup script deploy automatically
-
-    File Location: force-app/main/default/cspTrustedSites/{{APIName}}.cspTrustedSite-meta.xml
--->
-<CspTrustedSite xmlns="http://soap.sforce.com/2006/04/metadata">
-    <!-- API Name - must be unique, alphanumeric only -->
-    <fullName>{{APIName}}</fullName>
-
-    <!-- Description - what this endpoint is for -->
-    <description>{{Description}}</description>
-
-    <!-- Endpoint URL - the base domain (no trailing slash) -->
-    <!-- Examples:
-         - https://api.stripe.com
-         - https://api.twilio.com
-         - https://graph.microsoft.com
-    -->
-    <endpointUrl>{{BaseURL}}</endpointUrl>
-
-    <!-- Active - set to true to enable -->
-    <isActive>true</isActive>
-
-    <!--
-    Context: Where this trusted site applies
-
-    Available contexts:
-    - All: Apply to all contexts (recommended for most integrations)
-    - Connect: Apex HTTP callouts only
-    - Frame: iframe embedding
-    - Img: Image resources
-    - Script: JavaScript resources
-    - Style: CSS resources
-
-    For Apex HTTP callouts (most common), use either:
-    - "All" (simplest, covers everything)
-    - "Connect" (most specific, Apex callouts only)
-    -->
-    <context>{{Context}}</context>
-</CspTrustedSite>

package/skills/building-sf-integrations/assets/endpoint-security/example.remoteSite-meta.xml

@@ -1,39 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
-    Remote Site Setting Template
-
-    Use this template when creating integration skills that make HTTP callouts
-    to external APIs.
-
-    IMPORTANT:
-    - This is the LEGACY approach (still works in all API versions)
-    - For API 48+ (Spring '20+), prefer CSP Trusted Sites (see example.cspTrustedSite-meta.xml)
-
-    Setup:
-    1. Copy this file to your skill's assets/ directory
-    2. Replace {{placeholders}} with your values
-    3. Deploy to org OR let setup script deploy automatically
-
-    File Location: force-app/main/default/remoteSiteSettings/{{APIName}}.remoteSite-meta.xml
--->
-<RemoteSiteSetting xmlns="http://soap.sforce.com/2006/04/metadata">
-    <!-- API Name - must be unique, alphanumeric only -->
-    <fullName>{{APIName}}</fullName>
-
-    <!-- Description - what this endpoint is for -->
-    <description>{{Description}}</description>
-
-    <!-- Security - ALWAYS keep this false (don't allow HTTP, only HTTPS) -->
-    <disableProtocolSecurity>false</disableProtocolSecurity>
-
-    <!-- Active - set to true to enable -->
-    <isActive>true</isActive>
-
-    <!-- URL - the base domain (no path, no trailing slash) -->
-    <!-- Examples:
-         - https://api.stripe.com
-         - https://api.twilio.com
-         - https://graph.microsoft.com
-    -->
-    <url>{{BaseURL}}</url>
-</RemoteSiteSetting>