@salesforce/afv-skills 1.5.0 → 1.5.2

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

@@ -0,0 +1,92 @@
+/**
+ * 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 ────────────────────────────────────────────────────
+
+    /**
+     * 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);
+    }
+
+    /**
+     * 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 ─────────────────────────────────────────────
+
+    /**
+     * 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 ─────────────────────────────────────────────────
+
+    /**
+     * 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));
+            }
+        }
+    }
+
+    /**
+     * 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/rest-resource.cls

@@ -0,0 +1,300 @@
+/**
+ * REST API endpoint for {SObject} operations.
+ *              Exposes CRUD operations via @RestResource at /services/apexrest/{urlPath}/v1/*.
+ *              Uses versioned URL mapping for future-proof API evolution.
+ *              All queries use WITH USER_MODE for CRUD/FLS enforcement.
+ *
+ * Authentication: OAuth 2.0 via Connected App
+ * Base URL: /services/apexrest/{urlPath}/v1/
+ */
+@RestResource(urlMapping='/{urlPath}/v1/*')
+global with sharing class {ClassName} {
+
+    // ─── Constants ────────────────────────────────────────────────────────
+    private static final Integer DEFAULT_PAGE_SIZE = 20;
+    private static final Integer MAX_PAGE_SIZE = 200;
+    private static final String ERROR_MISSING_ID = 'Record Id is required in the URL path.';
+    private static final String ERROR_INVALID_ID = 'Invalid Salesforce Id format.';
+    private static final String ERROR_MISSING_BODY = 'Request body is required.';
+    private static final String ERROR_NOT_FOUND = '{SObject} record not found.';
+    private static final String ERROR_INSUFFICIENT_ACCESS = 'Insufficient access to perform this operation.';
+
+    // ─── GET — Retrieve ───────────────────────────────────────────────────
+
+    /**
+     * Retrieves a single {SObject} by Id (URL path) or a paginated list (query params).
+     * Single: GET /services/apexrest/{urlPath}/v1/{recordId}
+     * List:   GET /services/apexrest/{urlPath}/v1?pageSize=20&offset=0
+     * @return ApiResponse containing the requested data
+     */
+    @HttpGet
+    global static ApiResponse doGet() {
+        RestRequest req = RestContext.request;
+        RestResponse res = RestContext.response;
+
+        try {
+            String recordId = extractIdFromUri(req.requestURI);
+
+            if (String.isNotBlank(recordId)) {
+                return getSingleRecord(recordId, res);
+            }
+            return getRecordList(req, res);
+
+        } catch (Exception e) {
+            return handleError(res, 500, e.getMessage());
+        }
+    }
+
+    // ─── POST — Create ───────────────────────────────────────────────────
+
+    /**
+     * Creates a new {SObject} record from the JSON request body.
+     * POST /services/apexrest/{urlPath}/v1/
+     * @return ApiResponse with the created record Id
+     */
+    @HttpPost
+    global static ApiResponse doPost() {
+        RestRequest req = RestContext.request;
+        RestResponse res = RestContext.response;
+
+        try {
+            if (req.requestBody == null || String.isBlank(req.requestBody.toString())) {
+                return handleError(res, 400, ERROR_MISSING_BODY);
+            }
+
+            {ClassName}Request payload = ({ClassName}Request) JSON.deserialize(
+                req.requestBody.toString(),
+                {ClassName}Request.class
+            );
+
+            // TODO: Map request payload to SObject fields
+            {SObject} record = new {SObject}(
+                Name = payload.name
+            );
+
+            Database.SaveResult saveResult = Database.insert(record, true);
+            if (saveResult.isSuccess()) {
+                res.statusCode = 201;
+                return new ApiResponse(true, 'Record created successfully.', record.Id);
+            }
+
+            return handleError(res, 422, saveResult.getErrors()[0].getMessage());
+
+        } catch (JSONException e) {
+            return handleError(res, 400, 'Malformed JSON: ' + e.getMessage());
+        } catch (DmlException e) {
+            return handleError(res, 422, 'Validation failed: ' + e.getDmlMessage(0));
+        } catch (Exception e) {
+            return handleError(res, 500, e.getMessage());
+        }
+    }
+
+    // ─── PATCH — Partial Update ───────────────────────────────────────────
+
+    /**
+     * Partially updates an existing {SObject} record.
+     * PATCH /services/apexrest/{urlPath}/v1/{recordId}
+     * @return ApiResponse confirming the update
+     */
+    @HttpPatch
+    global static ApiResponse doPatch() {
+        RestRequest req = RestContext.request;
+        RestResponse res = RestContext.response;
+
+        try {
+            String recordId = extractIdFromUri(req.requestURI);
+            if (String.isBlank(recordId)) {
+                return handleError(res, 400, ERROR_MISSING_ID);
+            }
+            if (!isValidSalesforceId(recordId)) {
+                return handleError(res, 400, ERROR_INVALID_ID);
+            }
+            if (req.requestBody == null || String.isBlank(req.requestBody.toString())) {
+                return handleError(res, 400, ERROR_MISSING_BODY);
+            }
+
+            List<{SObject}> existing = [
+                SELECT Id FROM {SObject} WHERE Id = :recordId WITH USER_MODE LIMIT 1
+            ];
+            if (existing.isEmpty()) {
+                return handleError(res, 404, ERROR_NOT_FOUND);
+            }
+
+            Map<String, Object> fieldUpdates = (Map<String, Object>) JSON.deserializeUntyped(
+                req.requestBody.toString()
+            );
+
+            {SObject} record = existing[0];
+            // TODO: Apply allowed field updates from the payload to the record
+            // for (String fieldName : fieldUpdates.keySet()) {
+            //     record.put(fieldName, fieldUpdates.get(fieldName));
+            // }
+
+            Database.SaveResult saveResult = Database.update(record, true);
+            if (saveResult.isSuccess()) {
+                res.statusCode = 200;
+                return new ApiResponse(true, 'Record updated successfully.', record.Id);
+            }
+
+            return handleError(res, 422, saveResult.getErrors()[0].getMessage());
+
+        } catch (JSONException e) {
+            return handleError(res, 400, 'Malformed JSON: ' + e.getMessage());
+        } catch (DmlException e) {
+            return handleError(res, 422, 'Validation failed: ' + e.getDmlMessage(0));
+        } catch (Exception e) {
+            return handleError(res, 500, e.getMessage());
+        }
+    }
+
+    // ─── DELETE — Remove ──────────────────────────────────────────────────
+
+    /**
+     * Deletes a {SObject} record by Id.
+     * DELETE /services/apexrest/{urlPath}/v1/{recordId}
+     * @return ApiResponse confirming the deletion
+     */
+    @HttpDelete
+    global static ApiResponse doDelete() {
+        RestRequest req = RestContext.request;
+        RestResponse res = RestContext.response;
+
+        try {
+            String recordId = extractIdFromUri(req.requestURI);
+            if (String.isBlank(recordId)) {
+                return handleError(res, 400, ERROR_MISSING_ID);
+            }
+            if (!isValidSalesforceId(recordId)) {
+                return handleError(res, 400, ERROR_INVALID_ID);
+            }
+
+            List<{SObject}> existing = [
+                SELECT Id FROM {SObject} WHERE Id = :recordId WITH USER_MODE LIMIT 1
+            ];
+            if (existing.isEmpty()) {
+                return handleError(res, 404, ERROR_NOT_FOUND);
+            }
+
+            Database.DeleteResult deleteResult = Database.delete(existing[0], true);
+            if (deleteResult.isSuccess()) {
+                res.statusCode = 200;
+                return new ApiResponse(true, 'Record deleted successfully.', recordId);
+            }
+
+            return handleError(res, 422, deleteResult.getErrors()[0].getMessage());
+
+        } catch (DmlException e) {
+            return handleError(res, 422, e.getDmlMessage(0));
+        } catch (Exception e) {
+            return handleError(res, 500, e.getMessage());
+        }
+    }
+
+    // ─── Private Helpers ──────────────────────────────────────────────────
+
+    private static ApiResponse getSingleRecord(String recordId, RestResponse res) {
+        if (!isValidSalesforceId(recordId)) {
+            return handleError(res, 400, ERROR_INVALID_ID);
+        }
+
+        List<{SObject}> records = [
+            SELECT Id, Name, CreatedDate, LastModifiedDate
+            FROM {SObject}
+            WHERE Id = :recordId
+            WITH USER_MODE
+            LIMIT 1
+        ];
+
+        if (records.isEmpty()) {
+            return handleError(res, 404, ERROR_NOT_FOUND);
+        }
+
+        res.statusCode = 200;
+        ApiResponse response = new ApiResponse(true, 'Record retrieved successfully.', recordId);
+        response.data = records[0];
+        return response;
+    }
+
+    private static ApiResponse getRecordList(RestRequest req, RestResponse res) {
+        Integer pageSize = getIntParam(req, 'pageSize', DEFAULT_PAGE_SIZE);
+        Integer offset = getIntParam(req, 'offset', 0);
+
+        pageSize = Math.min(pageSize, MAX_PAGE_SIZE);
+
+        List<{SObject}> records = [
+            SELECT Id, Name, CreatedDate, LastModifiedDate
+            FROM {SObject}
+            WITH USER_MODE
+            ORDER BY Name ASC
+            LIMIT :pageSize
+            OFFSET :offset
+        ];
+
+        res.statusCode = 200;
+        ApiResponse response = new ApiResponse(true, 'Records retrieved successfully.', null);
+        response.records = records;
+        response.pageSize = pageSize;
+        response.offset = offset;
+        return response;
+    }
+
+    private static String extractIdFromUri(String uri) {
+        String lastSegment = uri.substringAfterLast('/');
+        if (String.isBlank(lastSegment) || lastSegment == 'v1') {
+            return null;
+        }
+        return lastSegment;
+    }
+
+    private static Boolean isValidSalesforceId(String idValue) {
+        return Pattern.matches('[a-zA-Z0-9]{15,18}', idValue);
+    }
+
+    private static Integer getIntParam(RestRequest req, String paramName, Integer defaultValue) {
+        String paramValue = req.params.get(paramName);
+        if (String.isBlank(paramValue)) {
+            return defaultValue;
+        }
+        try {
+            return Integer.valueOf(paramValue);
+        } catch (TypeException e) {
+            return defaultValue;
+        }
+    }
+
+    private static ApiResponse handleError(RestResponse res, Integer statusCode, String message) {
+        res.statusCode = statusCode;
+        return new ApiResponse(false, message, null);
+    }
+
+    // ─── Request / Response DTOs ──────────────────────────────────────────
+
+    /**
+     * Inbound request payload for POST operations.
+     * Extend with additional fields as needed.
+     */
+    global class {ClassName}Request {
+        global String name;
+        // TODO: Add fields matching the expected JSON request body
+    }
+
+    /**
+     * Standardized API response envelope.
+     * All endpoints return this structure for consistent client parsing.
+     */
+    global class ApiResponse {
+        global Boolean success;
+        global String message;
+        global String recordId;
+        global SObject data;
+        global List<SObject> records;
+        global Integer pageSize;
+        global Integer offset;
+
+        global ApiResponse(Boolean success, String message, String recordId) {
+            this.success = success;
+            this.message = message;
+            this.recordId = recordId;
+        }
+    }
+}

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

@@ -0,0 +1,75 @@
+/**
+ * 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
+
+    /** Runs daily at 2:00 AM */
+    public static final String CRON_DAILY_2AM = '0 0 2 * * ?';
+
+    /** Runs every weekday at 6:00 AM */
+    public static final String CRON_WEEKDAYS_6AM = '0 0 6 ? * MON-FRI';
+
+    /** Runs hourly at the top of the hour */
+    public static final String CRON_HOURLY = '0 0 * * * ?';
+
+    // ─── Schedulable Interface ───────────────────────────────────────────
+
+    /**
+     * 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 ──────────────────────────────────
+
+    /**
+     * 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}()
+        );
+    }
+
+    /**
+     * 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 @@
+/**
+ * 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 inherited sharing class {SObject}Selector {
+
+    // ─── Field Lists ─────────────────────────────────────────────────────
+
+    /**
+     * 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 ───────────────────────────────────────────────────
+
+    /**
+     * 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'
+        );
+    }
+
+    /**
+     * 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));
+    }
+
+    /**
+     * 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 ───────────────────────────────────────────────────────
+
+    /**
+     * Custom exception for query errors
+     */
+    public class QueryException extends Exception {}
+}

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

@@ -0,0 +1,69 @@
+/**
+ * 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 ──────────────────────────────────────────────────────
+
+    /**
+     * {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 ───────────────────────────────────────────
+
+    /**
+     * 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 ───────────────────────────────────────────────────────
+
+    /**
+     * Custom exception for {SObject}Service errors
+     */
+    public class {SObject}ServiceException extends Exception {}
+}

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

@@ -0,0 +1,45 @@
+/**
+ * @author Generated by Apex Class Writer Skill
+ */
+trigger {SObject}Trigger on {SObject} (
+    before insert,
+    before update,
+    before delete,
+    after insert,
+    after update,
+    after delete,
+    after undelete
+) {
+    // ─── Option A: Trigger Actions Framework (TAF) ───────────────────────
+    // Delegates to Trigger_Action__mdt-registered action classes.
+    // Each action class handles one concern in one context.
+    //
+    // new MetadataTriggerHandler().run();
+
+    // ─── Option B: Custom Handler Pattern ────────────────────────────────
+    // Delegates to a single handler class that routes by context.
+    //
+    // {SObject}TriggerHandler handler = new {SObject}TriggerHandler();
+    //
+    // if (Trigger.isBefore) {
+    //     if (Trigger.isInsert) {
+    //         handler.beforeInsert(Trigger.new);
+    //     } else if (Trigger.isUpdate) {
+    //         handler.beforeUpdate(Trigger.new, Trigger.oldMap);
+    //     } else if (Trigger.isDelete) {
+    //         handler.beforeDelete(Trigger.old, Trigger.oldMap);
+    //     }
+    // } else if (Trigger.isAfter) {
+    //     if (Trigger.isInsert) {
+    //         handler.afterInsert(Trigger.new, Trigger.newMap);
+    //     } else if (Trigger.isUpdate) {
+    //         handler.afterUpdate(Trigger.new, Trigger.oldMap);
+    //     } else if (Trigger.isDelete) {
+    //         handler.afterDelete(Trigger.old, Trigger.oldMap);
+    //     } else if (Trigger.isUndelete) {
+    //         handler.afterUndelete(Trigger.new, Trigger.newMap);
+    //     }
+    // }
+
+    // TODO: Uncomment one option above and remove the other
+}