@salesforce/afv-skills 1.4.0 → 1.5.1

package/skills/generating-apex/assets/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);
+    }
+}

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

@@ -0,0 +1,51 @@
+/**
+ * @description Custom exception for {describe when this exception is thrown}.
+ *              Use this exception to signal domain-specific errors that callers
+ *              can catch and handle distinctly from system exceptions.
+ * @author Generated by Apex Class Writer Skill
+ *
+ * @example
+ * throw new {ClassName}('Account merge failed: duplicate detected.');
+ *
+ * // Wrap a caught exception
+ * try {
+ *     // ... risky operation
+ * } catch (DmlException e) {
+ *     throw new {ClassName}('DML failed during account merge: ' + e.getMessage());
+ * }
+ */
+public with sharing class {ClassName} extends Exception {
+    // Apex custom exceptions automatically inherit:
+    //   - getMessage()
+    //   - getCause()
+    //   - getStackTraceString()
+    //   - setMessage(String)
+    //   - initCause(Exception)
+    //
+    // And support these constructor patterns:
+    //   - new {ClassName}()
+    //   - new {ClassName}('message')
+    //   - new {ClassName}(causeException)
+    //   - new {ClassName}('message', causeException)
+    //
+    // Note: Apex does NOT support custom constructors on Exception subclasses.
+    // To add context, use the message string or create a wrapper pattern:
+    //
+    // Example wrapper pattern (if you need structured error data):
+    //
+    // public class {ClassName}Detail {
+    //     public String errorCode;
+    //     public List<Id> failedRecordIds;
+    //     public String detail;
+    //
+    //     public {ClassName}Detail(String errorCode, List<Id> failedRecordIds, String detail) {
+    //         this.errorCode = errorCode;
+    //         this.failedRecordIds = failedRecordIds;
+    //         this.detail = detail;
+    //     }
+    //
+    //     public override String toString() {
+    //         return '[' + errorCode + '] ' + detail + ' (Records: ' + failedRecordIds + ')';
+    //     }
+    // }
+}

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

@@ -0,0 +1,25 @@
+/**
+ * @description Interface for {describe the capability or contract this interface defines}.
+ *              Implement this interface to provide {describe what implementations do}.
+ * @author Generated by Apex Class Writer Skill
+ *
+ * @example
+ * public class EmailNotificationService implements {InterfaceName} {
+ *     public void execute(Map<String, Object> params) {
+ *         // Implementation
+ *     }
+ * }
+ */
+public interface {InterfaceName} {
+
+    /**
+     * @description {Describe what this method should do}
+     * @param params {Describe the parameter}
+     * @return {Describe the return value}
+     */
+    // TODO: Define interface methods
+    // Example:
+    // void execute(Map<String, Object> params);
+    // Boolean isEligible(SObject record);
+    // List<SObject> process(List<SObject> records);
+}

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

@@ -0,0 +1,92 @@
+/**
+ * @description Queueable Apex class for {describe the async operation}.
+ *              Accepts data through the constructor for stateful processing.
+ *              Optionally implements Database.AllowsCallouts for external integrations.
+ * @author Generated by Apex Class Writer Skill
+ *
+ * @example
+ * // Enqueue the job
+ * Id jobId = System.enqueueJob(new {ClassName}(recordIds));
+ */
+public with sharing class {ClassName} implements Queueable /*, Database.AllowsCallouts */ {
+
+    // ─── Constants ───────────────────────────────────────────────────────
+    private static final Integer MAX_CHAIN_DEPTH = 5;
+
+    // ─── Instance Variables (Stateful) ───────────────────────────────────
+    private Set<Id> recordIds;
+    private Integer chainDepth;
+
+    // ─── Constructors ────────────────────────────────────────────────────
+
+    /**
+     * @description Creates a new queueable job to process the specified records
+     * @param recordIds Set of record Ids to process
+     */
+    public {ClassName}(Set<Id> recordIds) {
+        this(recordIds, 0);
+    }
+
+    /**
+     * @description Creates a new queueable job with chain depth tracking
+     * @param recordIds Set of record Ids to process
+     * @param chainDepth Current depth in the queueable chain
+     */
+    public {ClassName}(Set<Id> recordIds, Integer chainDepth) {
+        this.recordIds = recordIds ?? new Set<Id>();
+        this.chainDepth = chainDepth;
+    }
+
+    // ─── Queueable Interface ─────────────────────────────────────────────
+
+    /**
+     * @description Executes the asynchronous work
+     * @param context The queueable context
+     */
+    public void execute(QueueableContext context) {
+        if (this.recordIds.isEmpty()) {
+            return;
+        }
+
+        try {
+            // TODO: Implement the async processing logic
+            // List<{SObject}> records = {SObject}Selector.selectByIds(this.recordIds);
+            // ... process records ...
+
+            // Chain to next job if there's more work and we haven't hit the depth limit
+            chainIfNeeded();
+
+        } catch (Exception e) {
+            handleError(context.getJobId(), e);
+        }
+    }
+
+    // ─── Private Helpers ─────────────────────────────────────────────────
+
+    /**
+     * @description Chains to the next queueable job if needed, with depth guard
+     */
+    private void chainIfNeeded() {
+        // TODO: Determine if chaining is needed (e.g., remaining records to process)
+        Set<Id> remainingIds = new Set<Id>();
+
+        if (!remainingIds.isEmpty() && this.chainDepth < MAX_CHAIN_DEPTH) {
+            if (!Test.isRunningTest()) {
+                System.enqueueJob(new {ClassName}(remainingIds, this.chainDepth + 1));
+            }
+        }
+    }
+
+    /**
+     * @description Handles errors during execution
+     * @param jobId The async job Id
+     * @param e The exception that occurred
+     */
+    private void handleError(Id jobId, Exception e) {
+        System.debug(LoggingLevel.ERROR,
+            '{ClassName} failed (Job: ' + jobId + '): ' +
+            e.getMessage() + '\n' + e.getStackTraceString()
+        );
+        // TODO: Persist error to a log object or send notification
+    }
+}

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

@@ -0,0 +1,75 @@
+/**
+ * @description Schedulable Apex class for {describe the scheduled operation}.
+ *              Delegates heavy processing to a Batch or Queueable job.
+ *              Keep execute() lightweight — it should only launch other jobs.
+ * @author Generated by Apex Class Writer Skill
+ *
+ * @example
+ * // Schedule to run daily at 2 AM
+ * String jobId = System.schedule(
+ *     '{ClassName} - Daily',
+ *     {ClassName}.CRON_DAILY_2AM,
+ *     new {ClassName}()
+ * );
+ *
+ * // Or use the convenience method
+ * String jobId = {ClassName}.scheduleDaily();
+ */
+public with sharing class {ClassName} implements Schedulable {
+
+    // ─── CRON Expressions ────────────────────────────────────────────────
+    // Seconds Minutes Hours Day_of_month Month Day_of_week Optional_year
+
+    /** @description Runs daily at 2:00 AM */
+    public static final String CRON_DAILY_2AM = '0 0 2 * * ?';
+
+    /** @description Runs every weekday at 6:00 AM */
+    public static final String CRON_WEEKDAYS_6AM = '0 0 6 ? * MON-FRI';
+
+    /** @description Runs hourly at the top of the hour */
+    public static final String CRON_HOURLY = '0 0 * * * ?';
+
+    // ─── Schedulable Interface ───────────────────────────────────────────
+
+    /**
+     * @description Entry point for the scheduled execution.
+     *              Delegates to a Batch or Queueable for the actual work.
+     * @param sc The schedulable context
+     */
+    public void execute(SchedulableContext sc) {
+        // Option A: Launch a Batch job
+        // Database.executeBatch(new {BatchClassName}(), 200);
+
+        // Option B: Launch a Queueable job
+        // System.enqueueJob(new {QueueableClassName}(params));
+
+        // TODO: Implement delegation to appropriate async job
+    }
+
+    // ─── Convenience Scheduling Methods ──────────────────────────────────
+
+    /**
+     * @description Schedules this job to run daily at 2 AM
+     * @return The scheduled job Id
+     */
+    public static String scheduleDaily() {
+        return System.schedule(
+            '{ClassName} - Daily 2AM',
+            CRON_DAILY_2AM,
+            new {ClassName}()
+        );
+    }
+
+    /**
+     * @description Aborts this scheduled job by name
+     * @param jobName The name used when scheduling
+     */
+    public static void abort(String jobName) {
+        for (CronTrigger ct : [
+            SELECT Id FROM CronTrigger
+            WHERE CronJobDetail.Name = :jobName
+        ]) {
+            System.abortJob(ct.Id);
+        }
+    }
+}

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

@@ -0,0 +1,92 @@
+/**
+ * @description Selector class for {SObject} queries.
+ *              Encapsulates all SOQL for {SObject} records.
+ *              All methods return bulkified results (Lists or Maps).
+ * @author Generated by Apex Class Writer Skill
+ */
+public with sharing class {SObject}Selector {
+
+    // ─── Field Lists ─────────────────────────────────────────────────────
+
+    /**
+     * @description Returns the default set of fields to query for {SObject}.
+     *              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',
+                'CreatedDate',
+                'LastModifiedDate'
+                // TODO: Add additional fields here
+            },
+            ', '
+        );
+    }
+
+    // ─── Query Methods ───────────────────────────────────────────────────
+
+    /**
+     * @description Selects {SObject} records by their Ids
+     * @param recordIds Set of {SObject} Ids to query
+     * @return List of {SObject} records matching the provided Ids
+     * @example
+     * Set<Id> ids = new Set<Id>{ '001xx000003DGbY' };
+     * List<{SObject}> results = {SObject}Selector.selectByIds(ids);
+     */
+    public static List<{SObject}> selectByIds(Set<Id> recordIds) {
+        if (recordIds == null || recordIds.isEmpty()) {
+            return new List<{SObject}>();
+        }
+
+        return Database.query(
+            'SELECT ' + getDefaultFields() +
+            ' FROM {SObject}' +
+            ' WHERE Id IN :recordIds'
+        );
+    }
+
+    /**
+     * @description Selects {SObject} records as a Map keyed by Id
+     * @param recordIds Set of {SObject} Ids to query
+     * @return Map of Id to {SObject}
+     */
+    public static Map<Id, {SObject}> selectMapByIds(Set<Id> recordIds) {
+        return new Map<Id, {SObject}>(selectByIds(recordIds));
+    }
+
+    /**
+     * @description Selects {SObject} records by a specific field value
+     * @param fieldName API name of the field to filter on
+     * @param values Set of values to match
+     * @return List of matching {SObject} records
+     * @example
+     * List<{SObject}> results = {SObject}Selector.selectByField('Status__c', new Set<String>{ 'Active' });
+     */
+    public static List<{SObject}> selectByField(String fieldName, Set<String> values) {
+        if (String.isBlank(fieldName) || values == null || values.isEmpty()) {
+            return new List<{SObject}>();
+        }
+
+        // Validate field name to prevent SOQL injection
+        Schema.SObjectField field = Schema.SObjectType.{SObject}.fields.getMap().get(fieldName);
+        if (field == null) {
+            throw new QueryException('Invalid field name: ' + fieldName);
+        }
+
+        return Database.query(
+            'SELECT ' + getDefaultFields() +
+            ' FROM {SObject}' +
+            ' WHERE ' + String.escapeSingleQuotes(fieldName) + ' IN :values'
+        );
+    }
+
+    // ─── Exception ───────────────────────────────────────────────────────
+
+    /**
+     * @description Custom exception for query errors
+     */
+    public class QueryException extends Exception {}
+}

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

@@ -0,0 +1,69 @@
+/**
+ * @description Service class for {SObject} business logic.
+ *              Follows separation of concerns: delegates queries to {SObject}Selector
+ *              and SObject manipulation to {SObject}Domain where applicable.
+ * @author Generated by Apex Class Writer Skill
+ */
+public with sharing class {SObject}Service {
+
+    // ─── Constants ───────────────────────────────────────────────────────
+    private static final String ERROR_NULL_INPUT = 'Input cannot be null or empty.';
+
+    // ─── Public API ──────────────────────────────────────────────────────
+
+    /**
+     * @description {Describe the primary operation}
+     * @param recordIds Set of {SObject} Ids to process
+     * @return List of processed {SObject} records
+     * @throws {SObject}ServiceException if processing fails
+     * @example
+     * Set<Id> ids = new Set<Id>{ '001xx000003DGbY' };
+     * List<{SObject}> results = {SObject}Service.process{SObject}s(ids);
+     */
+    public static List<{SObject}> process{SObject}s(Set<Id> recordIds) {
+        // Guard clause
+        if (recordIds == null || recordIds.isEmpty()) {
+            throw new {SObject}ServiceException(ERROR_NULL_INPUT);
+        }
+
+        // Query via Selector
+        List<{SObject}> records = {SObject}Selector.selectByIds(recordIds);
+
+        // Apply business logic
+        // TODO: Implement business logic here
+
+        // DML
+        try {
+            update records;
+        } catch (DmlException e) {
+            throw new {SObject}ServiceException(
+                'Failed to update {SObject} records: ' + e.getMessage()
+            );
+        }
+
+        return records;
+    }
+
+    // ─── Convenience Overloads ───────────────────────────────────────────
+
+    /**
+     * @description Single-record convenience overload
+     * @param recordId The {SObject} Id to process
+     * @return The processed {SObject} record
+     */
+    public static {SObject} process{SObject}(Id recordId) {
+        List<{SObject}> results = process{SObject}s(new Set<Id>{ recordId });
+        return results.isEmpty() ? null : results[0];
+    }
+
+    // ─── Private Helpers ─────────────────────────────────────────────────
+
+    // TODO: Add private helper methods as needed
+
+    // ─── Exception ───────────────────────────────────────────────────────
+
+    /**
+     * @description Custom exception for {SObject}Service errors
+     */
+    public class {SObject}ServiceException extends Exception {}
+}

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

@@ -0,0 +1,97 @@
+/**
+ * @description 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 ─────────────────────────────────────────────
+
+    /**
+     * @description Prevents instantiation — use static methods only
+     */
+    @TestVisible
+    private {ClassName}() {
+        // Utility class — do not instantiate
+    }
+
+    // ─── Public Methods ──────────────────────────────────────────────────
+
+    // TODO: Add utility methods below. Examples:
+
+    /**
+     * @description 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;
+        }
+    }
+
+    /**
+     * @description 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;
+    }
+
+    /**
+     * @description 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;
+    }
+}