@salesforce/afv-skills 1.5.0 → 1.5.2

package/skills/generating-apex/assets/utility.cls

@@ -0,0 +1,97 @@
+/**
+ * Utility class for {describe the category of utilities: String, Date, Collection, etc.}.
+ *              All methods are static and side-effect-free (no SOQL, no DML).
+ *              Private constructor prevents instantiation.
+ * @author Generated by Apex Class Writer Skill
+ */
+public with sharing class {ClassName} {
+
+    // ─── Private Constructor ─────────────────────────────────────────────
+
+    /**
+     * Prevents instantiation — use static methods only
+     */
+    @TestVisible
+    private {ClassName}() {
+        // Utility class — do not instantiate
+    }
+
+    // ─── Public Methods ──────────────────────────────────────────────────
+
+    // TODO: Add utility methods below. Examples:
+
+    /**
+     * Safely converts a String to an Integer, returning a default if parsing fails
+     * @param value The String to parse
+     * @param defaultValue The fallback value if parsing fails
+     * @return The parsed Integer or the default value
+     * @example
+     * Integer result = {ClassName}.safeParseInteger('42', 0); // returns 42
+     * Integer result = {ClassName}.safeParseInteger('abc', 0); // returns 0
+     */
+    public static Integer safeParseInteger(String value, Integer defaultValue) {
+        if (String.isBlank(value)) {
+            return defaultValue;
+        }
+        try {
+            return Integer.valueOf(value.trim());
+        } catch (TypeException e) {
+            return defaultValue;
+        }
+    }
+
+    /**
+     * Chunks a list into smaller sublists of the specified size.
+     *              Useful for processing records in governor-limit-safe batches.
+     * @param items The list to chunk
+     * @param chunkSize The maximum size of each chunk
+     * @return A list of sublists, each containing up to chunkSize elements
+     * @example
+     * List<List<String>> chunks = {ClassName}.chunkList(myList, 200);
+     */
+    public static List<List<Object>> chunkList(List<Object> items, Integer chunkSize) {
+        List<List<Object>> chunks = new List<List<Object>>();
+        if (items == null || items.isEmpty() || chunkSize <= 0) {
+            return chunks;
+        }
+
+        List<Object> currentChunk = new List<Object>();
+        for (Object item : items) {
+            currentChunk.add(item);
+            if (currentChunk.size() == chunkSize) {
+                chunks.add(currentChunk);
+                currentChunk = new List<Object>();
+            }
+        }
+
+        if (!currentChunk.isEmpty()) {
+            chunks.add(currentChunk);
+        }
+
+        return chunks;
+    }
+
+    /**
+     * Extracts a Set of non-null field values from a list of SObjects
+     * @param records The SObject records to extract from
+     * @param fieldName The API name of the field to extract
+     * @return A Set of non-null String values
+     * @example
+     * Set<String> emails = {ClassName}.pluckStrings(contacts, 'Email');
+     */
+    public static Set<String> pluckStrings(List<SObject> records, String fieldName) {
+        Set<String> values = new Set<String>();
+        if (records == null || String.isBlank(fieldName)) {
+            return values;
+        }
+
+        for (SObject record : records) {
+            Object val = record.get(fieldName);
+            if (val != null) {
+                values.add(String.valueOf(val));
+            }
+        }
+
+        return values;
+    }
+}

package/skills/generating-apex/references/AccountDeduplicationBatch.cls

@@ -0,0 +1,148 @@
+/**
+ * Batch Apex class for identifying and flagging duplicate Account records.
+ *              Compares Accounts by Name and BillingPostalCode to find potential duplicates.
+ *              Flags duplicates by setting the Is_Potential_Duplicate__c checkbox.
+ *              Implements Database.Stateful to track results across batch chunks.
+ * @author Generated by Apex Class Writer Skill
+ *
+ * @example
+ * // Run with default batch size (200)
+ * Id jobId = AccountDeduplicationBatch.run();
+ *
+ * // Run with smaller batch size for complex processing
+ * Database.executeBatch(new AccountDeduplicationBatch(), 50);
+ */
+public with sharing class AccountDeduplicationBatch implements Database.Batchable<SObject>, Database.Stateful {
+
+    // ─── Constants ───────────────────────────────────────────────────────
+    private static final Integer DEFAULT_BATCH_SIZE = 200;
+
+    // ─── Stateful Tracking ───────────────────────────────────────────────
+    private Integer totalScanned = 0;
+    private Integer duplicatesFound = 0;
+    private Integer totalErrors = 0;
+    private List<String> errorMessages = new List<String>();
+
+    // ─── Batchable Interface ─────────────────────────────────────────────
+
+    /**
+     * Queries all active Accounts that haven't already been flagged
+     * @param bc The batch context
+     * @return QueryLocator scoped to unflagged active Accounts
+     */
+    public Database.QueryLocator start(Database.BatchableContext bc) {
+        return Database.getQueryLocator([
+            SELECT Id, Name, BillingPostalCode, Is_Potential_Duplicate__c
+            FROM Account
+            WHERE IsDeleted = FALSE
+            AND Is_Potential_Duplicate__c = FALSE
+            ORDER BY Name ASC
+        ]);
+    }
+
+    /**
+     * Processes each batch by building a duplicate key and checking for matches.
+     *              Uses a composite key of normalized Name + BillingPostalCode.
+     * @param bc The batch context
+     * @param scope List of Account records in the current batch
+     */
+    public void execute(Database.BatchableContext bc, List<Account> scope) {
+        totalScanned += scope.size();
+
+        // Build duplicate keys for this batch
+        Map<String, List<Account>> dupeKeyMap = new Map<String, List<Account>>();
+        for (Account acct : scope) {
+            String key = buildDuplicateKey(acct);
+            if (String.isNotBlank(key)) {
+                if (!dupeKeyMap.containsKey(key)) {
+                    dupeKeyMap.put(key, new List<Account>());
+                }
+                dupeKeyMap.get(key).add(acct);
+            }
+        }
+
+        // Flag records that share a key with another record
+        List<Account> toUpdate = new List<Account>();
+        for (String key : dupeKeyMap.keySet()) {
+            List<Account> group = dupeKeyMap.get(key);
+            if (group.size() > 1) {
+                for (Account acct : group) {
+                    toUpdate.add(new Account(
+                        Id = acct.Id,
+                        Is_Potential_Duplicate__c = true
+                    ));
+                }
+            }
+        }
+
+        if (!toUpdate.isEmpty()) {
+            List<Database.SaveResult> results = Database.update(toUpdate, false);
+            processResults(results);
+        }
+    }
+
+    /**
+     * Logs a summary of the deduplication batch run
+     * @param bc The batch context
+     */
+    public void finish(Database.BatchableContext bc) {
+        String summary = String.format(
+            'AccountDeduplicationBatch completed. Scanned: {0}, Duplicates flagged: {1}, Errors: {2}',
+            new List<Object>{ totalScanned, duplicatesFound, totalErrors }
+        );
+
+        System.debug(LoggingLevel.INFO, summary);
+
+        if (!errorMessages.isEmpty()) {
+            System.debug(LoggingLevel.ERROR, 'Error details:\n' + String.join(errorMessages, '\n'));
+        }
+    }
+
+    // ─── Private Helpers ─────────────────────────────────────────────────
+
+    /**
+     * Builds a normalized composite key for duplicate detection
+     * @param acct The Account record
+     * @return Normalized key string, or null if insufficient data
+     */
+    private String buildDuplicateKey(Account acct) {
+        if (String.isBlank(acct.Name)) {
+            return null;
+        }
+
+        String normalizedName = acct.Name.trim().toUpperCase().replaceAll('\\s+', ' ');
+        String postalCode = (acct.BillingPostalCode ?? '').trim().toUpperCase();
+
+        return normalizedName + '|' + postalCode;
+    }
+
+    /**
+     * Processes DML results, tracking successes and failures
+     * @param results List of Database.SaveResult from update operation
+     */
+    private void processResults(List<Database.SaveResult> results) {
+        for (Database.SaveResult sr : results) {
+            if (sr.isSuccess()) {
+                duplicatesFound++;
+            } else {
+                totalErrors++;
+                for (Database.Error err : sr.getErrors()) {
+                    errorMessages.add(
+                        'Record ' + sr.getId() + ': ' +
+                        err.getStatusCode() + ' - ' + err.getMessage()
+                    );
+                }
+            }
+        }
+    }
+
+    // ─── Static Helpers ──────────────────────────────────────────────────
+
+    /**
+     * Convenience method to execute with default batch size
+     * @return The batch job Id
+     */
+    public static Id run() {
+        return Database.executeBatch(new AccountDeduplicationBatch(), DEFAULT_BATCH_SIZE);
+    }
+}

package/skills/generating-apex/references/AccountSelector.cls

@@ -0,0 +1,193 @@
+/**
+ * Selector class for Account queries.
+ *              Encapsulates all SOQL for Account records.
+ *              All methods return bulkified results (Lists or Maps).
+ * @author Generated by Apex Class Writer Skill
+ */
+public with sharing class AccountSelector {
+
+    // ─── Field Lists ─────────────────────────────────────────────────────
+
+    /**
+     * Returns the default set of fields to query for Account.
+     *              Centralizes field references to keep queries DRY.
+     * @return Comma-separated field list as a String
+     */
+    private static String getDefaultFields() {
+        return String.join(
+            new List<String>{
+                'Id',
+                'Name',
+                'AccountNumber',
+                'Type',
+                'Industry',
+                'AnnualRevenue',
+                'NumberOfEmployees',
+                'Phone',
+                'Website',
+                'OwnerId',
+                'CreatedDate',
+                'LastModifiedDate'
+            },
+            ', '
+        );
+    }
+
+    /**
+     * Returns fields needed for billing/territory operations
+     * @return Comma-separated field list as a String
+     */
+    private static String getBillingFields() {
+        return String.join(
+            new List<String>{
+                'Id',
+                'Name',
+                'BillingStreet',
+                'BillingCity',
+                'BillingState',
+                'BillingPostalCode',
+                'BillingCountry',
+                'Territory__c'
+            },
+            ', '
+        );
+    }
+
+    // ─── Query Methods ───────────────────────────────────────────────────
+
+    /**
+     * Selects Account records by their Ids
+     * @param recordIds Set of Account Ids to query
+     * @return List of Account records matching the provided Ids
+     * @example
+     * Set<Id> ids = new Set<Id>{ '001xx000003DGbY' };
+     * List<Account> results = AccountSelector.selectByIds(ids);
+     */
+    public static List<Account> selectByIds(Set<Id> recordIds) {
+        if (recordIds == null || recordIds.isEmpty()) {
+            return new List<Account>();
+        }
+
+        return Database.query(
+            'SELECT ' + getDefaultFields() +
+            ' FROM Account' +
+            ' WHERE Id IN :recordIds'
+        );
+    }
+
+    /**
+     * Selects Account records as a Map keyed by Id
+     * @param recordIds Set of Account Ids to query
+     * @return Map of Id to Account
+     */
+    public static Map<Id, Account> selectMapByIds(Set<Id> recordIds) {
+        return new Map<Id, Account>(selectByIds(recordIds));
+    }
+
+    /**
+     * Selects Accounts with billing address fields for territory assignment
+     * @param recordIds Set of Account Ids to query
+     * @return List of Account records with billing address fields populated
+     */
+    public static List<Account> selectWithBillingAddress(Set<Id> recordIds) {
+        if (recordIds == null || recordIds.isEmpty()) {
+            return new List<Account>();
+        }
+
+        return Database.query(
+            'SELECT ' + getBillingFields() +
+            ' FROM Account' +
+            ' WHERE Id IN :recordIds'
+        );
+    }
+
+    /**
+     * Selects Accounts by Account Type
+     * @param accountTypes Set of Account Type values to filter by
+     * @return List of matching Account records
+     * @example
+     * List<Account> prospects = AccountSelector.selectByType(
+     *     new Set<String>{ 'Prospect', 'Customer - Direct' }
+     * );
+     */
+    public static List<Account> selectByType(Set<String> accountTypes) {
+        if (accountTypes == null || accountTypes.isEmpty()) {
+            return new List<Account>();
+        }
+
+        return Database.query(
+            'SELECT ' + getDefaultFields() +
+            ' FROM Account' +
+            ' WHERE Type IN :accountTypes' +
+            ' ORDER BY Name ASC'
+        );
+    }
+
+    /**
+     * Selects Accounts by Industry with a minimum annual revenue
+     * @param industries Set of Industry values to filter by
+     * @param minRevenue Minimum AnnualRevenue threshold
+     * @return List of matching Account records ordered by revenue descending
+     * @example
+     * List<Account> techAccounts = AccountSelector.selectByIndustryAndRevenue(
+     *     new Set<String>{ 'Technology' },
+     *     1000000
+     * );
+     */
+    public static List<Account> selectByIndustryAndRevenue(Set<String> industries, Decimal minRevenue) {
+        if (industries == null || industries.isEmpty()) {
+            return new List<Account>();
+        }
+
+        Decimal revenueThreshold = minRevenue ?? 0;
+
+        return Database.query(
+            'SELECT ' + getDefaultFields() +
+            ' FROM Account' +
+            ' WHERE Industry IN :industries' +
+            ' AND AnnualRevenue >= :revenueThreshold' +
+            ' ORDER BY AnnualRevenue DESC'
+        );
+    }
+
+    /**
+     * Selects Accounts with their related Contacts (subquery)
+     * @param recordIds Set of Account Ids to query
+     * @return List of Account records with nested Contacts
+     */
+    public static List<Account> selectWithContacts(Set<Id> recordIds) {
+        if (recordIds == null || recordIds.isEmpty()) {
+            return new List<Account>();
+        }
+
+        return [
+            SELECT Id, Name, Type, Industry,
+                   (SELECT Id, FirstName, LastName, Email, Title
+                    FROM Contacts
+                    ORDER BY LastName ASC)
+            FROM Account
+            WHERE Id IN :recordIds
+        ];
+    }
+
+    // ─── Aggregate Queries ───────────────────────────────────────────────
+
+    /**
+     * Returns a count of Accounts grouped by Industry
+     * @return List of AggregateResult with Industry and record count
+     * @example
+     * List<AggregateResult> results = AccountSelector.countByIndustry();
+     * for (AggregateResult ar : results) {
+     *     System.debug(ar.get('Industry') + ': ' + ar.get('cnt'));
+     * }
+     */
+    public static List<AggregateResult> countByIndustry() {
+        return [
+            SELECT Industry, COUNT(Id) cnt
+            FROM Account
+            WHERE Industry != NULL
+            GROUP BY Industry
+            ORDER BY COUNT(Id) DESC
+        ];
+    }
+}

package/skills/generating-apex/references/AccountService.cls

@@ -0,0 +1,201 @@
+/**
+ * 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 ──────────────────────────────────────────────────────
+
+    /**
+     * 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;
+    }
+
+    /**
+     * 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 ───────────────────────────────────────────
+
+    /**
+     * 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 ─────────────────────────────────────────────────
+
+    /**
+     * 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;
+    }
+
+    /**
+     * 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();
+    }
+
+    /**
+     * 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;
+    }
+
+    /**
+     * 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 ───────────────────────────────────────────────────────
+
+    /**
+     * Custom exception for AccountService errors
+     */
+    public class AccountServiceException extends Exception {}
+}

package/skills/generating-apex-test/CREDITS.md

@@ -0,0 +1,30 @@
+# Credits & Acknowledgments
+
+This skill was influenced by the [sf-skills](https://github.com/Jaganpro/sf-skills) repository and built upon the collective wisdom of the Salesforce developer community. We gratefully acknowledge the following authors and resources whose ideas, patterns, and best practices have shaped this skill.
+
+---
+
+## Authors & Contributors
+
+### Jag Valaiyapathy (**[Jaganpro)](https://github.com/Jaganpro)**
+
+**[sf-skills](https://github.com/Jaganpro/sf-skills)**
+
+Key contributions influencing this skill:
+
+- Pioneering open-source Salesforce skills for agentic coding tools
+- Apex code generation and review patterns
+- Best practices, anti-patterns, and design patterns reference material
+- Template library for common Apex class types
+
+This skill was influenced by the [sf-skills](https://github.com/Jaganpro/sf-skills) repository.
+
+---
+
+## Special Thanks
+
+To the entire Salesforce developer community for sharing knowledge, writing blogs, creating open-source tools, and helping each other build better solutions.
+
+---
+
+*If we've missed anyone whose work influenced these skills, please let us know so we can add proper attribution.*