scc-universal 1.1.0

package/examples/flow-automation/README.md

@@ -0,0 +1,188 @@
+# Flow Automation Example
+
+Sample Record-Triggered Flow with best practices for review. API version 66.0 (Spring '26).
+
+## Structure
+
+```text
+force-app/main/default/flows/
+  Account_Set_Rating.flow-meta.xml
+```
+
+## Flow Design: Account Rating Auto-Set
+
+**Type:** Record-Triggered Flow (Before Save)
+**Object:** Account
+**When:** A record is created or updated
+**Why Before Save:** Same-record field updates in a Before Save flow require no extra DML statement, making it more efficient than After Save for this use case.
+
+### Logic
+
+1. **Entry Criteria:** Annual Revenue is not null AND has changed (prevents recursion)
+2. **Decision:** Evaluate revenue ranges (ordered most-specific first)
+   - Revenue > 1,000,000 → Set Rating = "Hot"
+   - Revenue > 100,000 → Set Rating = "Warm"
+   - Revenue <= 100,000 → Set Rating = "Cold"
+3. **Assignment:** Set the Rating field on `$Record` (no Update element needed in Before Save)
+
+## Flow Metadata
+
+```xml
+<!-- Account_Set_Rating.flow-meta.xml -->
+<?xml version="1.0" encoding="UTF-8"?>
+<Flow xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>66.0</apiVersion>
+    <description>Sets Account Rating based on Annual Revenue ranges.
+    Before-save flow — no DML needed for same-record updates.</description>
+    <interviewLabel>Account Set Rating {!$Flow.CurrentDateTime}</interviewLabel>
+    <label>Account Set Rating</label>
+    <processType>AutoLaunchedFlow</processType>
+    <status>Active</status>
+
+    <!-- Entry point: triggers on Account create/update -->
+    <start>
+        <locationX>50</locationX>
+        <locationY>0</locationY>
+        <connector>
+            <targetReference>Check_Revenue</targetReference>
+        </connector>
+        <filterFormula>
+            NOT(ISNULL({!$Record.AnnualRevenue}))
+            &amp;&amp; ISCHANGED({!$Record.AnnualRevenue})
+        </filterFormula>
+        <object>Account</object>
+        <recordTriggerType>CreateAndUpdate</recordTriggerType>
+        <triggerType>RecordBeforeSave</triggerType>
+    </start>
+
+    <!-- Decision: evaluate revenue ranges -->
+    <decisions>
+        <name>Check_Revenue</name>
+        <label>Check Revenue</label>
+        <locationX>182</locationX>
+        <locationY>158</locationY>
+        <defaultConnector>
+            <targetReference>Set_Rating_Cold</targetReference>
+        </defaultConnector>
+        <defaultConnectorLabel>Cold</defaultConnectorLabel>
+        <rules>
+            <name>Is_Hot</name>
+            <conditionLogic>and</conditionLogic>
+            <conditions>
+                <leftValueReference>$Record.AnnualRevenue</leftValueReference>
+                <operator>GreaterThan</operator>
+                <rightValue>
+                    <numberValue>1000000</numberValue>
+                </rightValue>
+            </conditions>
+            <connector>
+                <targetReference>Set_Rating_Hot</targetReference>
+            </connector>
+            <label>Hot</label>
+        </rules>
+        <rules>
+            <name>Is_Warm</name>
+            <conditionLogic>and</conditionLogic>
+            <conditions>
+                <leftValueReference>$Record.AnnualRevenue</leftValueReference>
+                <operator>GreaterThan</operator>
+                <rightValue>
+                    <numberValue>100000</numberValue>
+                </rightValue>
+            </conditions>
+            <connector>
+                <targetReference>Set_Rating_Warm</targetReference>
+            </connector>
+            <label>Warm</label>
+        </rules>
+    </decisions>
+
+    <!-- Assignment elements: set Rating on $Record (Before Save = no DML) -->
+    <assignments>
+        <name>Set_Rating_Hot</name>
+        <label>Set Rating Hot</label>
+        <locationX>50</locationX>
+        <locationY>334</locationY>
+        <assignmentItems>
+            <assignToReference>$Record.Rating</assignToReference>
+            <operator>Assign</operator>
+            <value>
+                <stringValue>Hot</stringValue>
+            </value>
+        </assignmentItems>
+    </assignments>
+    <assignments>
+        <name>Set_Rating_Warm</name>
+        <label>Set Rating Warm</label>
+        <locationX>182</locationX>
+        <locationY>334</locationY>
+        <assignmentItems>
+            <assignToReference>$Record.Rating</assignToReference>
+            <operator>Assign</operator>
+            <value>
+                <stringValue>Warm</stringValue>
+            </value>
+        </assignmentItems>
+    </assignments>
+    <assignments>
+        <name>Set_Rating_Cold</name>
+        <label>Set Rating Cold</label>
+        <locationX>314</locationX>
+        <locationY>334</locationY>
+        <assignmentItems>
+            <assignToReference>$Record.Rating</assignToReference>
+            <operator>Assign</operator>
+            <value>
+                <stringValue>Cold</stringValue>
+            </value>
+        </assignmentItems>
+    </assignments>
+</Flow>
+```
+
+### Review Checklist
+
+- [ ] Uses Record-Triggered Flow (not Process Builder or Workflow)
+- [ ] Entry criteria prevents unnecessary executions
+- [ ] Decision elements are ordered most-specific to least-specific
+- [ ] No DML operations inside loops
+- [ ] Bulkification-safe (handles 200+ records)
+- [ ] Error handling with fault paths
+- [ ] Description filled in for all elements
+- [ ] Flow is versioned (not overwriting active version)
+
+## Anti-Patterns to Avoid
+
+1. **Loops with DML** — Never put Create/Update/Delete inside a Loop element
+2. **Missing fault paths** — Always add fault connectors to DML elements
+3. **Recursive triggers** — Use `$Record__Prior` to check if values actually changed
+4. **Too many flows per object** — Consolidate into fewer flows with decision elements
+5. **Hardcoded values** — Use Custom Metadata or Custom Labels instead
+
+## Testing
+
+```apex
+@IsTest
+static void shouldSetRatingToHotForHighRevenue() {
+    Account acc = new Account(Name = 'Test', AnnualRevenue = 2000000);
+    insert acc;
+
+    Account result = [SELECT Rating FROM Account WHERE Id = :acc.Id];
+    System.assertEquals('Hot', result.Rating, 'High revenue should set rating to Hot');
+}
+
+@IsTest
+static void shouldSetRatingToColdForLowRevenue() {
+    Account acc = new Account(Name = 'Small Co', AnnualRevenue = 50000);
+    insert acc;
+
+    Account result = [SELECT Rating FROM Account WHERE Id = :acc.Id];
+    System.assertEquals('Cold', result.Rating, 'Low revenue should set rating to Cold');
+}
+```
+
+## SCC Skills
+
+- `sf-flow-development` -- Flow best practices and anti-patterns
+- `sf-governor-limits` -- verify flow doesn't accumulate DML in loops
+- `sf-apex-testing` -- write Apex tests that fire record-triggered flows

package/examples/integration-pattern/README.md

@@ -0,0 +1,416 @@
+# External Integration with Named Credentials
+
+Secure external API integration using Named Credentials, HTTP callout service, retry handling, async processing, and test mocking. Compatible with API version 66.0 (Spring '26).
+
+## When to Use This Pattern
+
+- Calling external REST APIs from Salesforce (payment gateways, ERPs, shipping providers)
+- Building callouts that need authentication managed by the platform
+- Implementing retry logic for transient network failures
+- Processing callouts asynchronously to avoid governor limits in synchronous contexts
+- Writing testable integration code with `HttpCalloutMock`
+
+## Structure
+
+```text
+force-app/main/default/
+  namedCredentials/
+    Payment_Gateway.namedCredential-meta.xml
+  externalCredentials/
+    Payment_Gateway_Credential.externalCredential-meta.xml
+  classes/
+    PaymentGatewayService.cls         # HTTP callout service
+    PaymentGatewayService_Test.cls    # Test with mock
+    PaymentGatewayQueueable.cls       # Async callout wrapper
+    PaymentGatewayMock.cls            # HttpCalloutMock implementation
+```
+
+## Named Credential Setup
+
+```xml
+<!-- Payment_Gateway.namedCredential-meta.xml -->
+<?xml version="1.0" encoding="UTF-8"?>
+<NamedCredential xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>Payment_Gateway</fullName>
+    <label>Payment Gateway</label>
+    <type>SecuredEndpoint</type>
+    <url>https://api.paymentgateway.example.com/v2</url>
+    <externalCredential>Payment_Gateway_Credential</externalCredential>
+    <allowMergeFieldsInBody>false</allowMergeFieldsInBody>
+    <allowMergeFieldsInHeader>false</allowMergeFieldsInHeader>
+    <generateAuthorizationHeader>true</generateAuthorizationHeader>
+</NamedCredential>
+```
+
+```xml
+<!-- Payment_Gateway_Credential.externalCredential-meta.xml -->
+<?xml version="1.0" encoding="UTF-8"?>
+<ExternalCredential xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>Payment_Gateway_Credential</fullName>
+    <label>Payment Gateway Credential</label>
+    <authenticationProtocol>Custom</authenticationProtocol>
+    <externalCredentialParameters>
+        <parameterName>Authorization</parameterName>
+        <parameterType>AuthHeader</parameterType>
+    </externalCredentialParameters>
+</ExternalCredential>
+```
+
+## HTTP Callout Service Class
+
+```apex
+public with sharing class PaymentGatewayService {
+
+    private static final String NAMED_CREDENTIAL = 'callout:Payment_Gateway';
+    private static final Integer DEFAULT_TIMEOUT = 30000; // 30 seconds
+
+    /**
+     * Charges a payment method. Returns a PaymentResult with success/failure details.
+     */
+    public static PaymentResult chargePayment(String paymentMethodId, Decimal amount, String currency_x) {
+        Map<String, Object> requestBody = new Map<String, Object>{
+            'payment_method' => paymentMethodId,
+            'amount' => (amount * 100).intValue(), // Convert to cents
+            'currency' => currency_x,
+            'capture' => true
+        };
+
+        HttpResponse response = sendRequest('POST', '/charges', JSON.serialize(requestBody));
+        return parsePaymentResponse(response);
+    }
+
+    /**
+     * Retrieves the status of an existing charge.
+     */
+    public static PaymentResult getChargeStatus(String chargeId) {
+        HttpResponse response = sendRequest('GET', '/charges/' + chargeId, null);
+        return parsePaymentResponse(response);
+    }
+
+    /**
+     * Core HTTP request method. All callouts route through here.
+     */
+    private static HttpResponse sendRequest(String method, String path, String body) {
+        HttpRequest req = new HttpRequest();
+        req.setEndpoint(NAMED_CREDENTIAL + path);
+        req.setMethod(method);
+        req.setTimeout(DEFAULT_TIMEOUT);
+        req.setHeader('Content-Type', 'application/json');
+        req.setHeader('Accept', 'application/json');
+        req.setHeader('Idempotency-Key', generateIdempotencyKey());
+
+        if (body != null) {
+            req.setBody(body);
+        }
+
+        Http http = new Http();
+        return http.send(req);
+    }
+
+    private static PaymentResult parsePaymentResponse(HttpResponse response) {
+        PaymentResult result = new PaymentResult();
+        result.statusCode = response.getStatusCode();
+
+        if (response.getStatusCode() == 200 || response.getStatusCode() == 201) {
+            Map<String, Object> responseBody = (Map<String, Object>) JSON.deserializeUntyped(response.getBody());
+            result.success = true;
+            result.chargeId = (String) responseBody.get('id');
+            result.status = (String) responseBody.get('status');
+        } else {
+            result.success = false;
+            result.errorMessage = 'HTTP ' + response.getStatusCode() + ': ' + response.getBody();
+        }
+
+        return result;
+    }
+
+    private static String generateIdempotencyKey() {
+        Blob randomBytes = Crypto.generateAesKey(128);
+        return EncodingUtil.convertToHex(randomBytes);
+    }
+
+    public class PaymentResult {
+        @AuraEnabled public Boolean success;
+        @AuraEnabled public String chargeId;
+        @AuraEnabled public String status;
+        @AuraEnabled public String errorMessage;
+        @AuraEnabled public Integer statusCode;
+    }
+}
+```
+
+## Retry and Error Handling
+
+```apex
+public with sharing class CalloutRetryHelper {
+
+    private static final Integer MAX_RETRIES = 3;
+    private static final Set<Integer> RETRYABLE_STATUS_CODES = new Set<Integer>{
+        408, 429, 500, 502, 503, 504
+    };
+
+    /**
+     * Executes an HTTP request with exponential backoff retry.
+     * Only retries on transient errors (5xx, 408, 429).
+     */
+    public static HttpResponse sendWithRetry(HttpRequest request) {
+        Integer attempts = 0;
+        HttpResponse response;
+        Http http = new Http();
+
+        while (attempts < MAX_RETRIES) {
+            attempts++;
+            try {
+                response = http.send(request);
+
+                if (!RETRYABLE_STATUS_CODES.contains(response.getStatusCode())) {
+                    return response;
+                }
+
+                System.debug(LoggingLevel.WARN,
+                    'Retryable status ' + response.getStatusCode()
+                    + ' on attempt ' + attempts + ' of ' + MAX_RETRIES
+                );
+            } catch (CalloutException e) {
+                System.debug(LoggingLevel.ERROR,
+                    'Callout exception on attempt ' + attempts + ': ' + e.getMessage()
+                );
+                if (attempts >= MAX_RETRIES) {
+                    throw e;
+                }
+            }
+
+            // Note: Apex does not support Thread.sleep(). In synchronous context,
+            // retries happen immediately. For true backoff, use Queueable chaining.
+        }
+
+        return response;
+    }
+
+    /**
+     * Logs a failed callout to a custom object for monitoring and replay.
+     */
+    public static void logFailedCallout(String endpoint, String method, String body,
+            Integer statusCode, String errorMessage) {
+        Integration_Log__c log = new Integration_Log__c(
+            Endpoint__c = endpoint,
+            Method__c = method,
+            Request_Body__c = body != null ? body.left(131072) : null, // Long text area limit
+            Status_Code__c = statusCode,
+            Error_Message__c = errorMessage,
+            Timestamp__c = Datetime.now(),
+            Status__c = 'Failed'
+        );
+        insert log;
+    }
+}
+```
+
+## Queueable for Async Callouts
+
+```apex
+public class PaymentGatewayQueueable implements Queueable, Database.AllowsCallouts {
+
+    private final Id opportunityId;
+    private final String paymentMethodId;
+    private final Decimal amount;
+    private final String currency_x;
+
+    public PaymentGatewayQueueable(Id opportunityId, String paymentMethodId,
+            Decimal amount, String currency_x) {
+        this.opportunityId = opportunityId;
+        this.paymentMethodId = paymentMethodId;
+        this.amount = amount;
+        this.currency_x = currency_x;
+    }
+
+    public void execute(QueueableContext context) {
+        try {
+            PaymentGatewayService.PaymentResult result =
+                PaymentGatewayService.chargePayment(paymentMethodId, amount, currency_x);
+
+            Opportunity opp = new Opportunity(Id = opportunityId);
+            if (result.success) {
+                opp.Payment_Status__c = 'Charged';
+                opp.Payment_Reference__c = result.chargeId;
+            } else {
+                opp.Payment_Status__c = 'Failed';
+                opp.Payment_Error__c = result.errorMessage;
+
+                CalloutRetryHelper.logFailedCallout(
+                    'Payment_Gateway/charges', 'POST',
+                    JSON.serialize(new Map<String, Object>{
+                        'payment_method' => paymentMethodId,
+                        'amount' => amount
+                    }),
+                    result.statusCode, result.errorMessage
+                );
+            }
+            update opp;
+        } catch (Exception e) {
+            CalloutRetryHelper.logFailedCallout(
+                'Payment_Gateway/charges', 'POST', null, null, e.getMessage()
+            );
+        }
+    }
+}
+```
+
+## Mock for Testing (HttpCalloutMock)
+
+```apex
+@IsTest
+public class PaymentGatewayMock implements HttpCalloutMock {
+
+    private final Integer statusCode;
+    private final String responseBody;
+
+    public PaymentGatewayMock(Integer statusCode, String responseBody) {
+        this.statusCode = statusCode;
+        this.responseBody = responseBody;
+    }
+
+    public HttpResponse respond(HttpRequest request) {
+        HttpResponse response = new HttpResponse();
+        response.setStatusCode(statusCode);
+        response.setBody(responseBody);
+        response.setHeader('Content-Type', 'application/json');
+        return response;
+    }
+
+    // Convenience factory methods for common scenarios
+    public static PaymentGatewayMock success() {
+        return new PaymentGatewayMock(200, JSON.serialize(new Map<String, Object>{
+            'id' => 'ch_test_123456',
+            'status' => 'succeeded',
+            'amount' => 5000,
+            'currency' => 'usd'
+        }));
+    }
+
+    public static PaymentGatewayMock failure() {
+        return new PaymentGatewayMock(402, JSON.serialize(new Map<String, Object>{
+            'error' => new Map<String, Object>{
+                'type' => 'card_error',
+                'message' => 'Your card was declined'
+            }
+        }));
+    }
+
+    public static PaymentGatewayMock serverError() {
+        return new PaymentGatewayMock(500, '{"error": "Internal server error"}');
+    }
+}
+```
+
+## Test Class
+
+```apex
+@IsTest
+private class PaymentGatewayService_Test {
+
+    @IsTest
+    static void testChargePayment_Success() {
+        Test.setMock(HttpCalloutMock.class, PaymentGatewayMock.success());
+
+        Test.startTest();
+        PaymentGatewayService.PaymentResult result =
+            PaymentGatewayService.chargePayment('pm_test_123', 50.00, 'usd');
+        Test.stopTest();
+
+        System.assertEquals(true, result.success);
+        System.assertEquals('ch_test_123456', result.chargeId);
+        System.assertEquals('succeeded', result.status);
+    }
+
+    @IsTest
+    static void testChargePayment_Failure() {
+        Test.setMock(HttpCalloutMock.class, PaymentGatewayMock.failure());
+
+        Test.startTest();
+        PaymentGatewayService.PaymentResult result =
+            PaymentGatewayService.chargePayment('pm_test_123', 50.00, 'usd');
+        Test.stopTest();
+
+        System.assertEquals(false, result.success);
+        System.assertEquals(402, result.statusCode);
+        System.assert(result.errorMessage.contains('402'));
+    }
+
+    @IsTest
+    static void testGetChargeStatus() {
+        Test.setMock(HttpCalloutMock.class, PaymentGatewayMock.success());
+
+        Test.startTest();
+        PaymentGatewayService.PaymentResult result =
+            PaymentGatewayService.getChargeStatus('ch_test_123456');
+        Test.stopTest();
+
+        System.assertEquals(true, result.success);
+    }
+
+    @IsTest
+    static void testQueueableCallout_Success() {
+        Opportunity opp = new Opportunity(
+            Name = 'Test Opp',
+            StageName = 'Closed Won',
+            CloseDate = Date.today()
+        );
+        insert opp;
+
+        Test.setMock(HttpCalloutMock.class, PaymentGatewayMock.success());
+
+        Test.startTest();
+        System.enqueueJob(
+            new PaymentGatewayQueueable(opp.Id, 'pm_test_123', 100.00, 'usd')
+        );
+        Test.stopTest();
+
+        Opportunity updated = [SELECT Payment_Status__c, Payment_Reference__c FROM Opportunity WHERE Id = :opp.Id];
+        System.assertEquals('Charged', updated.Payment_Status__c);
+        System.assertEquals('ch_test_123456', updated.Payment_Reference__c);
+    }
+
+    @IsTest
+    static void testRetryHelper_RetryableStatusCode() {
+        Test.setMock(HttpCalloutMock.class, PaymentGatewayMock.serverError());
+
+        HttpRequest req = new HttpRequest();
+        req.setEndpoint('callout:Payment_Gateway/charges');
+        req.setMethod('POST');
+        req.setBody('{}');
+
+        Test.startTest();
+        HttpResponse response = CalloutRetryHelper.sendWithRetry(req);
+        Test.stopTest();
+
+        // In test context, all retries return the same mock
+        System.assertEquals(500, response.getStatusCode());
+    }
+}
+```
+
+## Key Principles
+
+- Always use Named Credentials for external endpoints; never hardcode URLs or credentials in Apex
+- Route all HTTP requests through a single method for consistent headers, timeouts, and logging
+- Use idempotency keys for POST/PUT requests to prevent duplicate charges on retries
+- Implement callouts in `Queueable` (with `Database.AllowsCallouts`) to avoid governor limits in triggers
+- Create reusable `HttpCalloutMock` implementations with factory methods for common scenarios
+- Log failed callouts to a custom object for monitoring, alerting, and manual replay
+
+## Common Pitfalls
+
+- Hardcoding API keys or endpoints instead of using Named Credentials (security risk and deployment headache)
+- Making callouts in trigger context without wrapping in a `Queueable` or `@future` method
+- Not setting `Test.setMock` before making callouts in tests, which causes "uncommitted work pending" errors
+- Forgetting `Database.AllowsCallouts` on the `Queueable` class, which throws a runtime exception
+- Not handling non-JSON error responses (some APIs return HTML on 500 errors)
+- Exceeding the 100-callout-per-transaction limit in batch jobs without tracking callout count
+
+## SCC Skills
+
+- `/sf-security` -- verify Named Credential usage and no hardcoded secrets
+- `/sf-apex-best-practices` -- review callout service code for best practices
+- `/sf-tdd-workflow` -- write tests first using mock classes
+- `/sf-governor-limits` -- check callout limits in async and batch contexts