@salesforce/afv-skills 1.1.0

package/skills/apex-class/examples/AccountService.cls

@@ -0,0 +1,201 @@
+/**
+ * @description Service class for Account business logic.
+ *              Provides account deduplication, enrichment, and territory assignment.
+ *              Delegates queries to AccountSelector and SObject manipulation to AccountDomain.
+ * @author Generated by Apex Class Writer Skill
+ */
+public with sharing class AccountService {
+
+    // ─── Constants ───────────────────────────────────────────────────────
+    private static final String ERROR_NULL_INPUT = 'Input cannot be null or empty.';
+    private static final String ERROR_MERGE_FAILED = 'Account merge failed for master Id: ';
+    private static final Integer MAX_MERGE_BATCH = 3;
+
+    // ─── Public API ──────────────────────────────────────────────────────
+
+    /**
+     * @description Merges duplicate Account records into a master record.
+     *              The master record retains its field values; child records are reparented.
+     * @param masterIds Map of master Account Id to Set of duplicate Account Ids to merge
+     * @return List of master Account Ids that were successfully merged
+     * @throws AccountServiceException if merge processing fails
+     * @example
+     * Map<Id, Set<Id>> mergeMap = new Map<Id, Set<Id>>{
+     *     masterAcctId => new Set<Id>{ dupeId1, dupeId2 }
+     * };
+     * List<Id> mergedIds = AccountService.mergeAccounts(mergeMap);
+     */
+    public static List<Id> mergeAccounts(Map<Id, Set<Id>> mergeMap) {
+        if (mergeMap == null || mergeMap.isEmpty()) {
+            throw new AccountServiceException(ERROR_NULL_INPUT);
+        }
+
+        // Collect all Ids for a single query
+        Set<Id> allIds = new Set<Id>();
+        allIds.addAll(mergeMap.keySet());
+        for (Set<Id> dupeIds : mergeMap.values()) {
+            allIds.addAll(dupeIds);
+        }
+
+        // Query all records at once via Selector
+        Map<Id, Account> accountMap = AccountSelector.selectMapByIds(allIds);
+
+        List<Id> successfulMerges = new List<Id>();
+        List<String> errors = new List<String>();
+
+        for (Id masterId : mergeMap.keySet()) {
+            Account master = accountMap.get(masterId);
+            if (master == null) {
+                errors.add('Master account not found: ' + masterId);
+                continue;
+            }
+
+            List<Account> duplicates = new List<Account>();
+            for (Id dupeId : mergeMap.get(masterId)) {
+                Account dupe = accountMap.get(dupeId);
+                if (dupe != null) {
+                    duplicates.add(dupe);
+                }
+            }
+
+            try {
+                // Apex merge supports up to 3 records at a time
+                for (List<Account> chunk : chunkAccounts(duplicates, MAX_MERGE_BATCH)) {
+                    Database.merge(master, chunk);
+                }
+                successfulMerges.add(masterId);
+            } catch (DmlException e) {
+                errors.add(ERROR_MERGE_FAILED + masterId + ' - ' + e.getMessage());
+            }
+        }
+
+        if (!errors.isEmpty()) {
+            System.debug(LoggingLevel.WARN, 'Merge errors: ' + String.join(errors, '\n'));
+        }
+
+        return successfulMerges;
+    }
+
+    /**
+     * @description Assigns accounts to territories based on Billing State/Country.
+     *              Uses Custom Metadata Type (Territory_Mapping__mdt) for mappings.
+     * @param accountIds Set of Account Ids to assign territories for
+     * @return Number of accounts successfully updated
+     * @throws AccountServiceException if territory assignment fails
+     */
+    public static Integer assignTerritories(Set<Id> accountIds) {
+        if (accountIds == null || accountIds.isEmpty()) {
+            throw new AccountServiceException(ERROR_NULL_INPUT);
+        }
+
+        List<Account> accounts = AccountSelector.selectWithBillingAddress(accountIds);
+        Map<String, String> territoryMap = loadTerritoryMappings();
+
+        List<Account> toUpdate = new List<Account>();
+        for (Account acct : accounts) {
+            String key = buildTerritoryKey(acct.BillingState, acct.BillingCountry);
+            String territory = territoryMap.get(key);
+
+            if (territory != null && territory != acct.Territory__c) {
+                toUpdate.add(new Account(
+                    Id = acct.Id,
+                    Territory__c = territory
+                ));
+            }
+        }
+
+        if (!toUpdate.isEmpty()) {
+            List<Database.SaveResult> results = Database.update(toUpdate, false);
+            return countSuccesses(results);
+        }
+
+        return 0;
+    }
+
+    // ─── Convenience Overloads ───────────────────────────────────────────
+
+    /**
+     * @description Single-account territory assignment convenience method
+     * @param accountId The Account Id to assign a territory for
+     * @return 1 if updated, 0 if no change needed
+     */
+    public static Integer assignTerritory(Id accountId) {
+        return assignTerritories(new Set<Id>{ accountId });
+    }
+
+    // ─── Private Helpers ─────────────────────────────────────────────────
+
+    /**
+     * @description Loads territory mappings from Custom Metadata
+     * @return Map of territory key (State:Country) to territory name
+     */
+    private static Map<String, String> loadTerritoryMappings() {
+        Map<String, String> mappings = new Map<String, String>();
+        for (Territory_Mapping__mdt mapping : Territory_Mapping__mdt.getAll().values()) {
+            String key = buildTerritoryKey(mapping.State__c, mapping.Country__c);
+            mappings.put(key, mapping.Territory_Name__c);
+        }
+        return mappings;
+    }
+
+    /**
+     * @description Builds a consistent territory lookup key
+     * @param state The billing state
+     * @param country The billing country
+     * @return A normalized key string
+     */
+    private static String buildTerritoryKey(String state, String country) {
+        return (state ?? '').toUpperCase() + ':' + (country ?? '').toUpperCase();
+    }
+
+    /**
+     * @description Chunks a list of Accounts into sublists of the given size
+     * @param accounts The accounts to chunk
+     * @param chunkSize Maximum chunk size
+     * @return List of account sublists
+     */
+    private static List<List<Account>> chunkAccounts(List<Account> accounts, Integer chunkSize) {
+        List<List<Account>> chunks = new List<List<Account>>();
+        List<Account> current = new List<Account>();
+
+        for (Account acct : accounts) {
+            current.add(acct);
+            if (current.size() == chunkSize) {
+                chunks.add(current);
+                current = new List<Account>();
+            }
+        }
+        if (!current.isEmpty()) {
+            chunks.add(current);
+        }
+        return chunks;
+    }
+
+    /**
+     * @description Counts successful results from a DML operation
+     * @param results List of Database.SaveResult
+     * @return Count of successful operations
+     */
+    private static Integer countSuccesses(List<Database.SaveResult> results) {
+        Integer count = 0;
+        for (Database.SaveResult sr : results) {
+            if (sr.isSuccess()) {
+                count++;
+            } else {
+                for (Database.Error err : sr.getErrors()) {
+                    System.debug(LoggingLevel.WARN,
+                        'Update failed for ' + sr.getId() + ': ' + err.getMessage()
+                    );
+                }
+            }
+        }
+        return count;
+    }
+
+    // ─── Exception ───────────────────────────────────────────────────────
+
+    /**
+     * @description Custom exception for AccountService errors
+     */
+    public class AccountServiceException extends Exception {}
+}

package/skills/apex-class/templates/abstract.cls

@@ -0,0 +1,128 @@
+/**
+ * @description Abstract base class for {describe the family of classes this serves}.
+ *              Provides common behavior and defines extension points for subclasses.
+ *              Subclasses must implement the abstract methods to provide specific behavior.
+ * @author Generated by Apex Class Writer Skill
+ *
+ * @example
+ * // Extending this abstract class:
+ * public class SalesforceIntegrationService extends {ClassName} {
+ *     protected override String getEndpoint() {
+ *         return 'callout:Salesforce_API/services/data/v62.0';
+ *     }
+ *
+ *     protected override Map<String, String> getHeaders() {
+ *         return new Map<String, String>{
+ *             'Content-Type' => 'application/json'
+ *         };
+ *     }
+ * }
+ */
+public abstract with sharing class {ClassName} {
+
+    // ─── Constants ───────────────────────────────────────────────────────
+    private static final Integer DEFAULT_TIMEOUT_MS = 30000;
+
+    // ─── Protected State ─────────────────────────────────────────────────
+    protected Integer timeoutMs;
+
+    // ─── Constructor ─────────────────────────────────────────────────────
+
+    /**
+     * @description Initializes the base class with default configuration
+     */
+    protected {ClassName}() {
+        this.timeoutMs = DEFAULT_TIMEOUT_MS;
+    }
+
+    // ─── Abstract Methods (must be implemented by subclasses) ────────────
+
+    /**
+     * @description Returns the endpoint URL for this integration.
+     *              Subclasses must provide their specific endpoint.
+     * @return The endpoint URL as a String
+     */
+    protected abstract String getEndpoint();
+
+    /**
+     * @description Returns the HTTP headers for this integration.
+     *              Subclasses define their own required headers.
+     * @return Map of header name to header value
+     */
+    protected abstract Map<String, String> getHeaders();
+
+    // ─── Virtual Methods (can be overridden by subclasses) ───────────────
+
+    /**
+     * @description Hook called before the main operation executes.
+     *              Override to add pre-processing logic.
+     *              Default implementation does nothing.
+     * @param context Map of contextual data
+     */
+    protected virtual void beforeExecute(Map<String, Object> context) {
+        // Default: no-op — override in subclass if needed
+    }
+
+    /**
+     * @description Hook called after the main operation completes.
+     *              Override to add post-processing logic.
+     *              Default implementation does nothing.
+     * @param context Map of contextual data
+     * @param result The result from the operation
+     */
+    protected virtual void afterExecute(Map<String, Object> context, Object result) {
+        // Default: no-op — override in subclass if needed
+    }
+
+    // ─── Template Method (common workflow) ───────────────────────────────
+
+    /**
+     * @description Executes the operation using the template method pattern.
+     *              Calls beforeExecute → doExecute → afterExecute in sequence.
+     * @param context Map of data needed for the operation
+     * @return The result of the operation
+     */
+    public Object execute(Map<String, Object> context) {
+        beforeExecute(context);
+
+        Object result;
+        try {
+            result = doExecute(context);
+        } catch (Exception e) {
+            handleError(e);
+            throw e;
+        }
+
+        afterExecute(context, result);
+        return result;
+    }
+
+    // ─── Protected Helpers ───────────────────────────────────────────────
+
+    /**
+     * @description Core execution logic — override this for the main operation.
+     *              Default implementation throws — subclass must provide implementation.
+     * @param context Map of data needed for the operation
+     * @return The result of the operation
+     */
+    protected virtual Object doExecute(Map<String, Object> context) {
+        throw new UnsupportedOperationException(
+            'Subclass must override doExecute()'
+        );
+    }
+
+    /**
+     * @description Error handler called when doExecute throws.
+     *              Override to customize error handling (e.g., logging, retry).
+     * @param e The exception that was thrown
+     */
+    protected virtual void handleError(Exception e) {
+        System.debug(LoggingLevel.ERROR,
+            this.toString() + ' error: ' + e.getMessage() + '\n' + e.getStackTraceString()
+        );
+    }
+
+    // ─── Exception ───────────────────────────────────────────────────────
+
+    public class UnsupportedOperationException extends Exception {}
+}

package/skills/apex-class/templates/batch.cls

@@ -0,0 +1,125 @@
+/**
+ * @description Batch Apex class for {describe the batch operation}.
+ *              Processes {SObject} records in configurable batch sizes.
+ *              Implements Database.Stateful to track cumulative results across chunks.
+ * @author Generated by Apex Class Writer Skill
+ *
+ * @example
+ * // Execute with default batch size
+ * Database.executeBatch(new {ClassName}());
+ *
+ * // Execute with custom batch size
+ * Database.executeBatch(new {ClassName}(), 100);
+ */
+public with sharing class {ClassName} implements Database.Batchable<SObject>, Database.Stateful {
+
+    // ─── Constants ───────────────────────────────────────────────────────
+    private static final Integer DEFAULT_BATCH_SIZE = 200;
+
+    // ─── Stateful Tracking ───────────────────────────────────────────────
+    private Integer totalProcessed = 0;
+    private Integer totalErrors = 0;
+    private List<String> errorMessages = new List<String>();
+
+    // ─── Constructor ─────────────────────────────────────────────────────
+
+    /**
+     * @description Default constructor
+     */
+    public {ClassName}() {
+        // Default configuration
+    }
+
+    // ─── Batchable Interface ─────────────────────────────────────────────
+
+    /**
+     * @description Defines the scope of records to process.
+     *              Uses Database.QueryLocator for efficient large-dataset processing.
+     * @param bc The batch context
+     * @return QueryLocator for the records to process
+     */
+    public Database.QueryLocator start(Database.BatchableContext bc) {
+        return Database.getQueryLocator([
+            SELECT Id, Name
+            // TODO: Add fields needed for processing
+            FROM {SObject}
+            // TODO: Add WHERE clause to scope the records
+        ]);
+    }
+
+    /**
+     * @description Processes each batch of records.
+     *              Uses Database.update with allOrNone=false for partial success handling.
+     * @param bc The batch context
+     * @param scope List of {SObject} records in the current batch
+     */
+    public void execute(Database.BatchableContext bc, List<{SObject}> scope) {
+        List<{SObject}> recordsToUpdate = new List<{SObject}>();
+
+        for ({SObject} record : scope) {
+            // TODO: Apply business logic to each record
+            recordsToUpdate.add(record);
+        }
+
+        if (!recordsToUpdate.isEmpty()) {
+            List<Database.SaveResult> results = Database.update(recordsToUpdate, false);
+            processResults(results);
+        }
+    }
+
+    /**
+     * @description Performs post-processing after all batches complete.
+     *              Logs a summary of the batch execution.
+     * @param bc The batch context
+     */
+    public void finish(Database.BatchableContext bc) {
+        String summary = String.format(
+            '{0} completed. Processed: {1}, Errors: {2}',
+            new List<Object>{
+                {ClassName}.class.getName(),
+                totalProcessed,
+                totalErrors
+            }
+        );
+
+        System.debug(LoggingLevel.INFO, summary);
+
+        if (!errorMessages.isEmpty()) {
+            System.debug(LoggingLevel.ERROR, 'Error details: ' + String.join(errorMessages, '\n'));
+        }
+
+        // TODO: Send completion notification email or post to chatter if needed
+    }
+
+    // ─── Private Helpers ─────────────────────────────────────────────────
+
+    /**
+     * @description Processes Database.SaveResult list, tracking successes and failures
+     * @param results List of SaveResult from a DML operation
+     */
+    private void processResults(List<Database.SaveResult> results) {
+        for (Database.SaveResult result : results) {
+            if (result.isSuccess()) {
+                totalProcessed++;
+            } else {
+                totalErrors++;
+                for (Database.Error err : result.getErrors()) {
+                    errorMessages.add(
+                        'Record ' + result.getId() + ': ' +
+                        err.getStatusCode() + ' - ' + err.getMessage()
+                    );
+                }
+            }
+        }
+    }
+
+    // ─── Static Helpers ──────────────────────────────────────────────────
+
+    /**
+     * @description Convenience method to execute with default batch size
+     * @return The batch job Id
+     */
+    public static Id run() {
+        return Database.executeBatch(new {ClassName}(), DEFAULT_BATCH_SIZE);
+    }
+}

package/skills/apex-class/templates/domain.cls

@@ -0,0 +1,102 @@
+/**
+ * @description Domain class for {SObject}.
+ *              Encapsulates field-level defaults, derivations, and validations.
+ *              Operates only on in-memory SObject data — no SOQL or DML.
+ * @author Generated by Apex Class Writer Skill
+ */
+public with sharing class {SObject}Domain {
+
+    // ─── Constants ───────────────────────────────────────────────────────
+    // TODO: Add constants for default values, statuses, etc.
+
+    // ─── Field Defaults ──────────────────────────────────────────────────
+
+    /**
+     * @description Applies default field values to new {SObject} records.
+     *              Call this before insert to ensure consistent defaults.
+     * @param records List of {SObject} records to apply defaults to
+     */
+    public static void applyDefaults(List<{SObject}> records) {
+        if (records == null || records.isEmpty()) {
+            return;
+        }
+
+        for ({SObject} record : records) {
+            // TODO: Set default field values
+            // Example:
+            // if (record.Status__c == null) {
+            //     record.Status__c = DEFAULT_STATUS;
+            // }
+        }
+    }
+
+    // ─── Derivations ────────────────────────────────────────────────────
+
+    /**
+     * @description Derives calculated field values based on other fields.
+     *              Call this before insert and before update.
+     * @param records List of {SObject} records to derive values for
+     */
+    public static void deriveFields(List<{SObject}> records) {
+        if (records == null || records.isEmpty()) {
+            return;
+        }
+
+        for ({SObject} record : records) {
+            // TODO: Derive calculated field values
+            // Example:
+            // record.FullAddress__c = buildFullAddress(record);
+        }
+    }
+
+    // ─── Validations ────────────────────────────────────────────────────
+
+    /**
+     * @description Validates {SObject} records and adds errors for any violations.
+     *              Call this before insert and before update.
+     * @param records List of {SObject} records to validate
+     */
+    public static void validate(List<{SObject}> records) {
+        if (records == null || records.isEmpty()) {
+            return;
+        }
+
+        for ({SObject} record : records) {
+            // TODO: Add validation rules
+            // Example:
+            // if (String.isBlank(record.Name)) {
+            //     record.addError('Name is required.');
+            // }
+        }
+    }
+
+    // ─── Comparisons ────────────────────────────────────────────────────
+
+    /**
+     * @description Determines which fields have changed between old and new record versions.
+     *              Useful in before update context.
+     * @param oldRecord The previous version of the record
+     * @param newRecord The current version of the record
+     * @return Set of field API names that have changed
+     */
+    public static Set<String> getChangedFields({SObject} oldRecord, {SObject} newRecord) {
+        Set<String> changedFields = new Set<String>();
+
+        if (oldRecord == null || newRecord == null) {
+            return changedFields;
+        }
+
+        Map<String, Schema.SObjectField> fieldMap = Schema.SObjectType.{SObject}.fields.getMap();
+        for (String fieldName : fieldMap.keySet()) {
+            if (oldRecord.get(fieldName) != newRecord.get(fieldName)) {
+                changedFields.add(fieldName);
+            }
+        }
+
+        return changedFields;
+    }
+
+    // ─── Private Helpers ─────────────────────────────────────────────────
+
+    // TODO: Add private helper methods as needed
+}

package/skills/apex-class/templates/dto.cls

@@ -0,0 +1,108 @@
+/**
+ * @description Data Transfer Object for {describe the data this DTO represents}.
+ *              Used to pass structured data between layers without exposing SObjects.
+ *              Serialization-friendly for use with JSON.serialize/deserialize and API responses.
+ * @author Generated by Apex Class Writer Skill
+ *
+ * @example
+ * // Create from constructor
+ * {ClassName} dto = new {ClassName}('value1', 42);
+ *
+ * // Deserialize from JSON
+ * {ClassName} dto = ({ClassName}) JSON.deserialize(jsonString, {ClassName}.class);
+ */
+public with sharing class {ClassName} {
+
+    // ─── Properties ──────────────────────────────────────────────────────
+
+    /** @description {Describe this property} */
+    public String name { get; set; }
+
+    /** @description {Describe this property} */
+    public Id recordId { get; set; }
+
+    /** @description {Describe this property} */
+    public Boolean isActive { get; set; }
+
+    /** @description {Describe this property} */
+    public List<String> tags { get; set; }
+
+    // TODO: Add additional properties as needed
+
+    // ─── Constructors ────────────────────────────────────────────────────
+
+    /**
+     * @description No-arg constructor for deserialization compatibility
+     */
+    public {ClassName}() {
+        this.tags = new List<String>();
+        this.isActive = false;
+    }
+
+    /**
+     * @description Parameterized constructor for convenience
+     * @param name The name value
+     * @param recordId The associated record Id
+     */
+    public {ClassName}(String name, Id recordId) {
+        this();
+        this.name = name;
+        this.recordId = recordId;
+    }
+
+    // ─── Factory Methods ─────────────────────────────────────────────────
+
+    /**
+     * @description Creates a DTO instance from an SObject record
+     * @param record The source {SObject} record
+     * @return A populated {ClassName} instance
+     */
+    public static {ClassName} fromSObject(SObject record) {
+        if (record == null) {
+            return new {ClassName}();
+        }
+
+        {ClassName} dto = new {ClassName}();
+        dto.recordId = record.Id;
+        dto.name = (String) record.get('Name');
+        // TODO: Map additional fields
+
+        return dto;
+    }
+
+    /**
+     * @description Creates a list of DTOs from a list of SObject records
+     * @param records The source records
+     * @return List of populated {ClassName} instances
+     */
+    public static List<{ClassName}> fromSObjects(List<SObject> records) {
+        List<{ClassName}> dtos = new List<{ClassName}>();
+        if (records == null) {
+            return dtos;
+        }
+
+        for (SObject record : records) {
+            dtos.add(fromSObject(record));
+        }
+        return dtos;
+    }
+
+    // ─── Utility Methods ─────────────────────────────────────────────────
+
+    /**
+     * @description Serializes this DTO to a JSON string
+     * @return JSON representation of this DTO
+     */
+    public String toJson() {
+        return JSON.serialize(this);
+    }
+
+    /**
+     * @description Deserializes a JSON string into a {ClassName} instance
+     * @param jsonString The JSON string to deserialize
+     * @return A {ClassName} instance
+     */
+    public static {ClassName} fromJson(String jsonString) {
+        return ({ClassName}) JSON.deserialize(jsonString, {ClassName}.class);
+    }
+}