scc-universal 1.1.0

package/.cursor/skills/sf-apex-testing/SKILL.md

@@ -0,0 +1,407 @@
+---
+name: sf-apex-testing
+description: >-
+  Apex unit testing — test structure, TestDataFactory, governor limit testing, async testing, mocks, coverage. Use when writing tests or improving coverage. Do NOT use for TDD workflow or LWC Jest tests.
+---
+
+# Apex Testing
+
+Procedures and patterns for writing effective Apex tests. Constraint rules (never/always lists for test isolation, assertions, SeeAllData) live in `sf-testing-constraints`. This skill covers the _how_ — test structure, factories, mocks, async testing, and coverage strategies.
+
+Reference: @../_reference/TESTING_STANDARDS.md
+
+---
+
+## When to Use
+
+- When writing test classes for new Apex code before deploying to production
+- When existing tests pass but only cover happy paths
+- When a deployment fails with "insufficient code coverage" errors
+- When building mock patterns for callouts or dependency injection
+
+> **Related:** For the TDD workflow (red-green-refactor process), see `sf-tdd-workflow`.
+
+---
+
+## @isTest Annotation
+
+```apex
+@isTest
+private class AccountServiceTest {
+
+    @TestSetup
+    static void makeData() {
+        // Runs once before any test method in this class
+        // Each test method gets a fresh transaction with this data
+    }
+
+    @isTest
+    static void testCreateAccount_validData_createsSuccessfully() {
+        // Arrange / Act / Assert
+    }
+}
+```
+
+Test classes do not count toward coverage calculations but DO count toward the 6 MB Apex code character limit. Use `@TestVisible` to make private members accessible in tests without changing access modifiers.
+
+---
+
+## @TestSetup
+
+Runs once per test class. Each test method gets its own database rollback, so modifications in one test do not bleed into another.
+
+```apex
+@TestSetup
+static void makeData() {
+    Account acc = new Account(
+        Name              = 'Test Corp',
+        Type              = 'Customer',
+        AnnualRevenue     = 1000000,
+        Customer_Tier__c  = 'Standard'
+    );
+    insert acc;
+
+    List<Opportunity> opps = new List<Opportunity>();
+    for (Integer i = 0; i < 10; i++) {
+        opps.add(new Opportunity(
+            Name       = 'Test Opp ' + i,
+            AccountId  = acc.Id,
+            StageName  = i < 5 ? 'Prospecting' : 'Qualification',
+            CloseDate  = Date.today().addDays(30 + i),
+            Amount     = 5000 * (i + 1)
+        ));
+    }
+    insert opps;
+}
+```
+
+---
+
+## TestDataFactory Pattern
+
+A central factory class creates test records consistently across the test suite, preventing duplicated record-creation logic.
+
+```apex
+@isTest
+public class TestDataFactory {
+
+    public static Account createAccount() {
+        return createAccount(new Map<String, Object>());
+    }
+
+    public static Account createAccount(Map<String, Object> overrides) {
+        Account acc = new Account(
+            Name              = 'Test Account ' + generateUniqueString(),
+            Type              = 'Customer',
+            Industry          = 'Technology',
+            AnnualRevenue     = 500000,
+            Customer_Tier__c  = 'Standard'
+        );
+        applyOverrides(acc, overrides);
+        insert acc;
+        return acc;
+    }
+
+    public static List<Account> createAccounts(Integer count) {
+        List<Account> accounts = new List<Account>();
+        for (Integer i = 0; i < count; i++) {
+            accounts.add(new Account(
+                Name             = 'Bulk Test Account ' + i,
+                Type             = 'Customer',
+                Customer_Tier__c = 'Standard'
+            ));
+        }
+        insert accounts;
+        return accounts;
+    }
+
+    public static User createUserWithProfile(String profileName) {
+        Profile p = [SELECT Id FROM Profile WHERE Name = :profileName LIMIT 1];
+        User u = new User(
+            Alias            = 'tstuser',
+            Email            = generateUniqueString() + '@testfactory.example.com',
+            EmailEncodingKey = 'UTF-8',
+            LastName         = 'Testing',
+            LanguageLocaleKey = 'en_US',
+            LocaleSidKey     = 'en_US',
+            ProfileId        = p.Id,
+            TimeZoneSidKey   = 'America/Los_Angeles',
+            UserName         = generateUniqueString() + '@testfactory.example.com'
+        );
+        insert u;
+        return u;
+    }
+
+    private static Integer uniqueCounter = 0;
+
+    private static String generateUniqueString() {
+        return String.valueOf(++uniqueCounter) + '_' +
+               String.valueOf(Datetime.now().getTime()).right(6);
+    }
+
+    private static void applyOverrides(SObject record, Map<String, Object> overrides) {
+        for (String fieldName : overrides.keySet()) {
+            record.put(fieldName, overrides.get(fieldName));
+        }
+    }
+}
+```
+
+---
+
+## Test Structure: Arrange-Act-Assert
+
+Every test method follows three phases with a blank line between them.
+
+```apex
+@isTest
+static void testCalculateDiscount_premiumTier_returns20Percent() {
+    // Arrange
+    Account acc = TestDataFactory.createAccount(
+        new Map<String, Object>{ 'Customer_Tier__c' => 'Premium' }
+    );
+    Decimal orderAmount = 10000;
+
+    // Act
+    Test.startTest();
+    Decimal discount = DiscountCalculator.calculate(acc.Id, orderAmount);
+    Test.stopTest();
+
+    // Assert
+    Assert.areEqual(2000, discount,
+        'Premium tier accounts should receive a 20% discount on $10,000 orders');
+}
+```
+
+### Test Method Naming
+
+Format: `test{MethodName}_{scenario}_{expectedResult}`
+
+```
+testCalculateDiscount_premiumTier_returns20Percent()
+testCalculateDiscount_nullAmount_returnsZero()
+testCreateAccount_duplicateName_addsFieldError()
+```
+
+---
+
+## Governor Limit Testing
+
+Always test with 200 records (standard trigger batch size). A method that works with 1 record may fail at governor limits with 200.
+
+```apex
+@isTest
+static void testTrigger_bulkInsert_staysWithinLimits() {
+    List<Account> accounts = TestDataFactory.createAccounts(200);
+
+    List<Account> processed = [
+        SELECT Id, Customer_Tier__c FROM Account
+        WHERE Id IN :new Map<Id, Account>(accounts).keySet()
+    ];
+
+    System.assertEquals(200, processed.size(), 'All 200 accounts should be present');
+}
+```
+
+Use `Test.startTest()` / `Test.stopTest()` to reset governor limit counters, giving the code under test a fresh limit context.
+
+---
+
+## Exception Testing
+
+```apex
+@isTest
+static void testUpgradeToPremium_insufficientRevenue_throwsUpgradeException() {
+    Account acc = TestDataFactory.createAccount(
+        new Map<String, Object>{ 'AnnualRevenue' => 10000 }
+    );
+
+    Test.startTest();
+    try {
+        AccountsService.upgradeToPremium(new Set<Id>{ acc.Id });
+        Assert.fail('Expected UpgradeException was not thrown');
+    } catch (AccountsService.UpgradeException e) {
+        Assert.isTrue(
+            e.getMessage().contains('Annual revenue must be at least'),
+            'Exception message should explain the reason. Got: ' + e.getMessage()
+        );
+    }
+    Test.stopTest();
+}
+```
+
+Use the `Assert` class (see @../_reference/API_VERSIONS.md for minimum version): `Assert.areEqual`, `Assert.isTrue`, `Assert.isNotNull`, `Assert.fail`.
+
+---
+
+## Permission Testing with System.runAs
+
+```apex
+@isTest
+static void testViewRestrictedReport_standardUser_throwsException() {
+    User standardUser = TestDataFactory.createUserWithProfile('Standard User');
+    Restricted_Report__c report = new Restricted_Report__c(Name = 'Confidential Q4');
+    insert report;
+
+    Test.startTest();
+    System.runAs(standardUser) {
+        try {
+            ReportService.viewReport(report.Id);
+            Assert.fail('Standard user should not be able to view restricted reports');
+        } catch (ReportService.AccessDeniedException e) {
+            Assert.isTrue(true, 'Expected AccessDeniedException thrown correctly');
+        }
+    }
+    Test.stopTest();
+}
+```
+
+---
+
+## Async Testing
+
+### @future and Queueable
+
+`Test.startTest()` / `Test.stopTest()` forces @future and Queueable jobs to execute synchronously.
+
+```apex
+@isTest
+static void testFutureCallout_sendsRequest() {
+    Test.setMock(HttpCalloutMock.class, new MockERPCallout(200, '{"status":"ok"}'));
+    Account acc = TestDataFactory.createAccount();
+
+    Test.startTest();
+    ExternalDataSync.syncAccountToERP(acc.Id);
+    Test.stopTest();
+
+    List<Integration_Error_Log__c> errors = [
+        SELECT Id FROM Integration_Error_Log__c WHERE Account__c = :acc.Id
+    ];
+    System.assertEquals(0, errors.size(), 'No errors should be logged');
+}
+```
+
+### Batch Apex
+
+```apex
+@isTest
+static void testBatch_processesAllRecords() {
+    // insert 200 records
+    Test.startTest();
+    Database.executeBatch(new AccountAnnualReviewBatch(), 200);
+    Test.stopTest(); // start(), execute(), finish() all run synchronously
+    // Assert results
+}
+```
+
+---
+
+## Mock Patterns
+
+### HttpCalloutMock
+
+```apex
+@isTest
+public class MockERPCallout implements HttpCalloutMock {
+    private Integer statusCode;
+    private String responseBody;
+
+    public MockERPCallout(Integer statusCode, String responseBody) {
+        this.statusCode   = statusCode;
+        this.responseBody = responseBody;
+    }
+
+    public HttpResponse respond(HttpRequest req) {
+        HttpResponse res = new HttpResponse();
+        res.setStatusCode(statusCode);
+        res.setBody(responseBody);
+        res.setHeader('Content-Type', 'application/json');
+        return res;
+    }
+}
+```
+
+### Multi-Callout Mock
+
+```apex
+@isTest
+public class MultiCalloutMock implements HttpCalloutMock {
+    private Map<String, HttpResponse> responses = new Map<String, HttpResponse>();
+
+    public MultiCalloutMock addResponse(String urlPattern, Integer statusCode, String body) {
+        HttpResponse res = new HttpResponse();
+        res.setStatusCode(statusCode);
+        res.setBody(body);
+        responses.put(urlPattern, res);
+        return this;
+    }
+
+    public HttpResponse respond(HttpRequest req) {
+        for (String pattern : responses.keySet()) {
+            if (req.getEndpoint().contains(pattern)) {
+                return responses.get(pattern);
+            }
+        }
+        throw new CalloutException('No mock response configured for: ' + req.getEndpoint());
+    }
+}
+```
+
+### Stub API (System.StubProvider)
+
+For mocking dependencies without HTTP, use the `System.StubProvider` interface with `Test.createStub()`.
+
+```apex
+IAccountsSelector mockSelector = (IAccountsSelector)
+    Test.createStub(IAccountsSelector.class, new MockAccountsSelector(mockAccounts));
+```
+
+> **Note:** The instance field must be typed as the interface (e.g., `IAccountsSelector`), not the concrete class. Casting a stub proxy to a concrete class throws TypeException at runtime.
+
+---
+
+## Coverage Strategy
+
+Line coverage is misleading. A method with an `if` statement can show 100% line coverage if you only test the `true` branch. Test every branch.
+
+```apex
+// This method has 4 branches — test each:
+// 1. testCalculateDiscount_premiumTier
+// 2. testCalculateDiscount_standardTier
+// 3. testCalculateDiscount_unknownTier (else)
+// 4. testCalculateDiscount_nullTier
+public Decimal calculateDiscount(String tier, Decimal amount) {
+    if (tier == 'Premium') return amount * 0.20;
+    else if (tier == 'Standard') return amount * 0.10;
+    else return 0;
+}
+```
+
+---
+
+## RunRelevantTests and @testFor (Spring '26)
+
+> Requires the minimum API version for this feature (see @../_reference/API_VERSIONS.md). If `sfdx-project.json` specifies a `sourceApiVersion` below it, `RunRelevantTests` silently falls back to `RunLocalTests`.
+
+`@testFor` explicitly declares which production class a test class covers, improving `RunRelevantTests` selection accuracy.
+
+```apex
+@isTest
+@testFor(AccountService)
+private class AccountServiceTest {
+    // tests for AccountService
+}
+```
+
+**Rules:** Reference any top-level Apex class (not inner classes). Cannot be placed on non-test classes. Use separate test classes for each target — Apex does not support stacking duplicate annotations.
+
+---
+
+## Related
+
+- **Agent**: `sf-apex-agent` — For interactive, in-depth guidance
+- **Skills**: `sf-tdd-workflow` — TDD workflow for Apex
+
+### Guardrails
+
+- `sf-testing-constraints` — Enforces test isolation, assertion requirements, SeeAllData prohibition, and coverage thresholds

package/.cursor/skills/sf-api-design/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: sf-api-design
+description: >-
+  Salesforce API design — custom REST endpoints, batch operations, Composite API, error envelopes, auth. Use when designing APIs exposed from Salesforce. Do NOT use for outbound callouts or Platform Events.
+---
+
+# Salesforce API Design
+
+Patterns for designing and implementing custom APIs on the Salesforce platform. Callout limits, Composite API limits, and Named Credential details live in the reference file.
+
+@../_reference/INTEGRATION_PATTERNS.md
+
+## When to Use
+
+- Designing custom REST or SOAP APIs exposed from Salesforce using Apex
+- Establishing consistent API response envelopes and error handling patterns
+- Configuring authentication for inbound API access
+- Building batch REST endpoints for bulk operations
+- Reviewing Apex API code for security (CRUD/FLS, input validation, status codes)
+
+---
+
+## Custom REST API Pattern
+
+```apex
+@RestResource(urlMapping='/api/accounts/*')
+global with sharing class AccountAPI {
+
+    @HttpGet
+    global static void getAccount() {
+        RestRequest req = RestContext.request;
+        RestResponse res = RestContext.response;
+
+        String accountId = req.requestURI.substringAfterLast('/');
+
+        try {
+            Account acc = [
+                SELECT Id, Name, Industry, AnnualRevenue
+                FROM Account WHERE Id = :accountId
+                WITH USER_MODE LIMIT 1
+            ];
+
+            res.statusCode = 200;
+            res.responseBody = Blob.valueOf(JSON.serialize(
+                new ApiResponse(true, acc, null)));
+        } catch (QueryException e) {
+            res.statusCode = 404;
+            res.responseBody = Blob.valueOf(JSON.serialize(
+                new ApiResponse(false, null, 'Account not found')));
+        } catch (Exception e) {
+            res.statusCode = 500;
+            res.responseBody = Blob.valueOf(JSON.serialize(
+                new ApiResponse(false, null, 'An internal error occurred')));
+        }
+    }
+
+    @HttpPost
+    global static void createAccount() {
+        RestRequest req = RestContext.request;
+        RestResponse res = RestContext.response;
+
+        try {
+            Object parsed = JSON.deserializeUntyped(req.requestBody.toString());
+            if (!(parsed instanceof Map<String, Object>)) {
+                res.statusCode = 400;
+                res.responseBody = Blob.valueOf(JSON.serialize(
+                    new ApiResponse(false, null,
+                        'Expected JSON object, got ' +
+                        (parsed instanceof List<Object> ? 'array' : 'primitive')
+                    )));
+                return;
+            }
+            Map<String, Object> body = (Map<String, Object>) parsed;
+            Account acc = new Account(
+                Name = (String) body.get('name'),
+                Industry = (String) body.get('industry')
+            );
+
+            // stripInaccessible — check getRemovedFields() to avoid silent data loss
+            SObjectAccessDecision decision = Security.stripInaccessible(
+                AccessType.CREATABLE, new List<Account>{acc});
+            if (!decision.getRemovedFields().isEmpty()) {
+                res.statusCode = 403;
+                res.responseBody = Blob.valueOf(JSON.serialize(
+                    new ApiResponse(false, null,
+                        'Insufficient field permissions for: ' +
+                        decision.getRemovedFields())));
+                return;
+            }
+            insert decision.getRecords();
+
+            res.statusCode = 201;
+            res.responseBody = Blob.valueOf(JSON.serialize(
+                new ApiResponse(true, decision.getRecords()[0], null)));
+        } catch (Exception e) {
+            res.statusCode = 400;
+            res.responseBody = Blob.valueOf(JSON.serialize(
+                new ApiResponse(false, null, e.getMessage())));
+        }
+    }
+
+    global class ApiResponse {
+        public Boolean success;
+        public Object data;
+        public String error;
+
+        public ApiResponse(Boolean success, Object data, String error) {
+            this.success = success;
+            this.data = data;
+            this.error = error;
+        }
+    }
+}
+```
+
+---
+
+## Batch REST Endpoint Pattern
+
+```apex
+@HttpPost
+global static void bulkCreate() {
+    RestRequest req = RestContext.request;
+    RestResponse res = RestContext.response;
+
+    try {
+        List<Object> items = (List<Object>) JSON.deserializeUntyped(
+            req.requestBody.toString());
+        List<Account> accounts = new List<Account>();
+
+        for (Object item : items) {
+            Map<String, Object> fields = (Map<String, Object>) item;
+            accounts.add(new Account(
+                Name = (String) fields.get('name'),
+                Industry = (String) fields.get('industry')
+            ));
+        }
+
+        SObjectAccessDecision decision = Security.stripInaccessible(
+            AccessType.CREATABLE, accounts);
+        List<Database.SaveResult> results =
+            Database.insert(decision.getRecords(), false);
+
+        List<Object> response = new List<Object>();
+        for (Integer i = 0; i < results.size(); i++) {
+            Map<String, Object> row = new Map<String, Object>();
+            row.put('index', i);
+            row.put('success', results[i].isSuccess());
+            row.put('id', results[i].isSuccess() ? results[i].getId() : null);
+            if (!results[i].isSuccess()) {
+                row.put('errors', results[i].getErrors()[0].getMessage());
+            }
+            response.add(row);
+        }
+
+        res.statusCode = 200;
+        res.responseBody = Blob.valueOf(JSON.serialize(
+            new ApiResponse(true, response, null)));
+    } catch (Exception e) {
+        res.statusCode = 400;
+        res.responseBody = Blob.valueOf(JSON.serialize(
+            new ApiResponse(false, null, e.getMessage())));
+    }
+}
+```
+
+---
+
+## Error Handling Patterns
+
+Structured error codes for API consumers:
+
+```apex
+global class ApiError {
+    public String code;
+    public String message;
+    public String field;
+
+    public ApiError(String code, String message, String field) {
+        this.code = code;
+        this.message = message;
+        this.field = field;
+    }
+}
+
+// Standard error codes:
+// FIELD_REQUIRED     — Missing required field
+// RECORD_NOT_FOUND   — Record ID doesn't exist or no access
+// GOVERNOR_LIMIT     — Operation would exceed governor limits
+// INSUFFICIENT_ACCESS — User lacks CRUD/FLS permission
+// VALIDATION_FAILED  — Validation rule or trigger prevented save
+// DUPLICATE_VALUE    — Unique field constraint violated
+```
+
+---
+
+## Authentication for Inbound APIs
+
+| Method | Use When | Setup |
+|--------|----------|-------|
+| Named Principal | All API users share one Salesforce user | Connected App + single auth |
+| Per-User | Each API caller maps to a Salesforce user | Connected App + OAuth per user |
+| JWT Bearer | Server-to-server, no user interaction | Connected App + X.509 certificate |
+| API Key (Custom) | Simple external tools | Custom Metadata + header validation |
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|-------------|---------|-----|
+| God endpoint (all CRUD in one method) | Hard to maintain and test | One method per operation (@HttpGet, @HttpPost) |
+| No pagination | Timeouts, governor limits | Add LIMIT + OFFSET or cursor-based pagination |
+| Exposing internal Salesforce IDs | Security risk, breaks across orgs | Use external IDs or custom identifiers |
+| No error codes | Consumers can't programmatically handle errors | Return structured error codes |
+| No API versioning | Breaking changes affect all consumers | Version via URL path: `/api/v1/accounts/` |
+| `WITHOUT SHARING` on API class | Bypasses record-level security | Use `WITH SHARING` on REST resources |
+| Returning all fields | Wastes bandwidth, exposes sensitive data | Return only requested/needed fields |
+
+---
+
+## Best Practices
+
+- Use `WITH USER_MODE` in SOQL and `AccessLevel.USER_MODE` in DML
+- Use `Security.stripInaccessible()` when you need field-level enforcement on DML -- check `getRemovedFields()` for critical fields
+- Return consistent response envelopes (success, data, error)
+- Use proper HTTP status codes (200, 201, 400, 404, 500)
+- Implement rate limiting awareness (API request limits)
+- Version APIs via URL path (`/api/v1/accounts/`)
+- Use `Database.insert(records, false)` for bulk APIs to support partial success
+
+---
+
+## Related
+
+- Constraints: sf-security-constraints
+- Reference: @../_reference/INTEGRATION_PATTERNS.md