@salesforce/afv-skills 1.5.1 → 1.5.3

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

@@ -1,8 +1,7 @@
 /**
- * @description Schedulable Apex class for {describe the scheduled operation}.
+ * 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
@@ -20,19 +19,19 @@ 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 */
+    /** Runs daily at 2:00 AM */
     public static final String CRON_DAILY_2AM = '0 0 2 * * ?';
 
-    /** @description Runs every weekday at 6:00 AM */
+    /** 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 */
+    /** 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.
+     * Entry point for the scheduled execution.
      *              Delegates to a Batch or Queueable for the actual work.
      * @param sc The schedulable context
      */
@@ -49,7 +48,7 @@ public with sharing class {ClassName} implements Schedulable {
     // ─── Convenience Scheduling Methods ──────────────────────────────────
 
     /**
-     * @description Schedules this job to run daily at 2 AM
+     * Schedules this job to run daily at 2 AM
      * @return The scheduled job Id
      */
     public static String scheduleDaily() {
@@ -61,7 +60,7 @@ public with sharing class {ClassName} implements Schedulable {
     }
 
     /**
-     * @description Aborts this scheduled job by name
+     * Aborts this scheduled job by name
      * @param jobName The name used when scheduling
      */
     public static void abort(String jobName) {

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

@@ -1,15 +1,14 @@
 /**
- * @description Selector class for {SObject} queries.
+ * 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 {
+public inherited sharing class {SObject}Selector {
 
     // ─── Field Lists ─────────────────────────────────────────────────────
 
     /**
-     * @description Returns the default set of fields to query for {SObject}.
+     * 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
      */
@@ -29,7 +28,7 @@ public with sharing class {SObject}Selector {
     // ─── Query Methods ───────────────────────────────────────────────────
 
     /**
-     * @description Selects {SObject} records by their Ids
+     * Selects {SObject} records by their Ids
      * @param recordIds Set of {SObject} Ids to query
      * @return List of {SObject} records matching the provided Ids
      * @example
@@ -49,7 +48,7 @@ public with sharing class {SObject}Selector {
     }
 
     /**
-     * @description Selects {SObject} records as a Map keyed by Id
+     * Selects {SObject} records as a Map keyed by Id
      * @param recordIds Set of {SObject} Ids to query
      * @return Map of Id to {SObject}
      */
@@ -58,7 +57,7 @@ public with sharing class {SObject}Selector {
     }
 
     /**
-     * @description Selects {SObject} records by a specific field value
+     * 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
@@ -86,7 +85,7 @@ public with sharing class {SObject}Selector {
     // ─── Exception ───────────────────────────────────────────────────────
 
     /**
-     * @description Custom exception for query errors
+     * Custom exception for query errors
      */
     public class QueryException extends Exception {}
 }

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

@@ -1,8 +1,7 @@
 /**
- * @description Service class for {SObject} business logic.
+ * 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 {
 
@@ -12,7 +11,7 @@ public with sharing class {SObject}Service {
     // ─── Public API ──────────────────────────────────────────────────────
 
     /**
-     * @description {Describe the primary operation}
+     * {Describe the primary operation}
      * @param recordIds Set of {SObject} Ids to process
      * @return List of processed {SObject} records
      * @throws {SObject}ServiceException if processing fails
@@ -47,7 +46,7 @@ public with sharing class {SObject}Service {
     // ─── Convenience Overloads ───────────────────────────────────────────
 
     /**
-     * @description Single-record convenience overload
+     * Single-record convenience overload
      * @param recordId The {SObject} Id to process
      * @return The processed {SObject} record
      */
@@ -63,7 +62,7 @@ public with sharing class {SObject}Service {
     // ─── Exception ───────────────────────────────────────────────────────
 
     /**
-     * @description Custom exception for {SObject}Service errors
+     * Custom exception for {SObject}Service errors
      */
     public class {SObject}ServiceException extends Exception {}
 }

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

@@ -0,0 +1,45 @@
+/**
+ * {SObject} Trigger
+ */
+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
+}

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

@@ -1,15 +1,14 @@
 /**
- * @description Utility class for {describe the category of utilities: String, Date, Collection, etc.}.
+ * 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
+     * Prevents instantiation — use static methods only
      */
     @TestVisible
     private {ClassName}() {
@@ -21,7 +20,7 @@ public with sharing class {ClassName} {
     // TODO: Add utility methods below. Examples:
 
     /**
-     * @description Safely converts a String to an Integer, returning a default if parsing fails
+     * 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
@@ -41,7 +40,7 @@ public with sharing class {ClassName} {
     }
 
     /**
-     * @description Chunks a list into smaller sublists of the specified size.
+     * 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
@@ -72,7 +71,7 @@ public with sharing class {ClassName} {
     }
 
     /**
-     * @description Extracts a Set of non-null field values from a list of SObjects
+     * 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

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

@@ -1,9 +1,8 @@
 /**
- * @description Batch Apex class for identifying and flagging duplicate Account records.
+ * 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)
@@ -26,7 +25,7 @@ public with sharing class AccountDeduplicationBatch implements Database.Batchabl
     // ─── Batchable Interface ─────────────────────────────────────────────
 
     /**
-     * @description Queries all active Accounts that haven't already been flagged
+     * Queries all active Accounts that haven't already been flagged
      * @param bc The batch context
      * @return QueryLocator scoped to unflagged active Accounts
      */
@@ -41,7 +40,7 @@ public with sharing class AccountDeduplicationBatch implements Database.Batchabl
     }
 
     /**
-     * @description Processes each batch by building a duplicate key and checking for matches.
+     * 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
@@ -82,7 +81,7 @@ public with sharing class AccountDeduplicationBatch implements Database.Batchabl
     }
 
     /**
-     * @description Logs a summary of the deduplication batch run
+     * Logs a summary of the deduplication batch run
      * @param bc The batch context
      */
     public void finish(Database.BatchableContext bc) {
@@ -101,7 +100,7 @@ public with sharing class AccountDeduplicationBatch implements Database.Batchabl
     // ─── Private Helpers ─────────────────────────────────────────────────
 
     /**
-     * @description Builds a normalized composite key for duplicate detection
+     * Builds a normalized composite key for duplicate detection
      * @param acct The Account record
      * @return Normalized key string, or null if insufficient data
      */
@@ -117,7 +116,7 @@ public with sharing class AccountDeduplicationBatch implements Database.Batchabl
     }
 
     /**
-     * @description Processes DML results, tracking successes and failures
+     * Processes DML results, tracking successes and failures
      * @param results List of Database.SaveResult from update operation
      */
     private void processResults(List<Database.SaveResult> results) {
@@ -139,7 +138,7 @@ public with sharing class AccountDeduplicationBatch implements Database.Batchabl
     // ─── Static Helpers ──────────────────────────────────────────────────
 
     /**
-     * @description Convenience method to execute with default batch size
+     * Convenience method to execute with default batch size
      * @return The batch job Id
      */
     public static Id run() {