@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/building-sf-integrations/references/rest-callout-patterns.md

@@ -0,0 +1,288 @@
+<!-- Parent: building-sf-integrations/SKILL.md -->
+# REST Callout Patterns
+
+## Overview
+
+This guide covers patterns for making HTTP callouts from Salesforce Apex to external REST APIs.
+
+## Synchronous vs Asynchronous
+
+### When to Use Synchronous
+
+- User needs immediate response
+- Called from Visualforce, LWC, or Aura
+- NOT triggered by DML operations
+- Response required before next action
+
+### When to Use Asynchronous
+
+- Called from triggers (REQUIRED)
+- Fire-and-forget operations
+- Background processing
+- Long-running operations
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  CALLOUT CONTEXT DECISION                                       │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  Is this called from a trigger or after DML?                    │
+│  ├── YES → Use Queueable with Database.AllowsCallouts          │
+│  └── NO  → Synchronous OK                                       │
+│                                                                 │
+│  Does user need immediate response?                             │
+│  ├── YES → Synchronous (if allowed)                            │
+│  └── NO  → Consider async for better UX                         │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Basic Request Pattern
+
+```apex
+public class RestCallout {
+
+    public static HttpResponse makeRequest(String method, String endpoint, String body) {
+        HttpRequest req = new HttpRequest();
+        req.setEndpoint('callout:MyCredential' + endpoint);
+        req.setMethod(method);
+        req.setHeader('Content-Type', 'application/json');
+        req.setHeader('Accept', 'application/json');
+        req.setTimeout(120000); // 120 seconds max
+
+        if (String.isNotBlank(body)) {
+            req.setBody(body);
+        }
+
+        return new Http().send(req);
+    }
+}
+```
+
+## HTTP Methods
+
+| Method | Use Case | Body |
+|--------|----------|------|
+| GET | Retrieve resource | No |
+| POST | Create resource | Yes |
+| PUT | Full update | Yes |
+| PATCH | Partial update | Yes |
+| DELETE | Remove resource | Usually No |
+
+## Response Handling
+
+### Status Code Categories
+
+```apex
+Integer statusCode = response.getStatusCode();
+
+if (statusCode >= 200 && statusCode < 300) {
+    // Success (2xx)
+} else if (statusCode >= 400 && statusCode < 500) {
+    // Client error (4xx) - don't retry
+} else if (statusCode >= 500) {
+    // Server error (5xx) - may retry
+}
+```
+
+### Common Status Codes
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| 200 | OK | Process response |
+| 201 | Created | Resource created |
+| 204 | No Content | Success, no body |
+| 400 | Bad Request | Fix request |
+| 401 | Unauthorized | Check credentials |
+| 403 | Forbidden | Check permissions |
+| 404 | Not Found | Resource doesn't exist |
+| 429 | Too Many Requests | Rate limited, retry later |
+| 500 | Server Error | Retry with backoff |
+| 503 | Service Unavailable | Retry later |
+
+## Error Handling Pattern
+
+```apex
+public class ApiClient {
+
+    public static Map<String, Object> callApi(String endpoint) {
+        try {
+            HttpResponse res = makeRequest('GET', endpoint, null);
+
+            if (res.getStatusCode() == 200) {
+                return (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
+            }
+
+            // Handle specific errors
+            if (res.getStatusCode() == 404) {
+                throw new NotFoundException('Resource not found: ' + endpoint);
+            }
+
+            if (res.getStatusCode() == 429) {
+                String retryAfter = res.getHeader('Retry-After');
+                throw new RateLimitedException('Rate limited. Retry after: ' + retryAfter);
+            }
+
+            throw new ApiException('API Error: ' + res.getStatusCode() + ' - ' + res.getBody());
+
+        } catch (CalloutException e) {
+            // Network error, timeout, SSL error
+            throw new ApiException('Connection failed: ' + e.getMessage(), e);
+        }
+    }
+
+    public class ApiException extends Exception {}
+    public class NotFoundException extends Exception {}
+    public class RateLimitedException extends Exception {}
+}
+```
+
+## Retry Pattern
+
+```apex
+public class RetryableCallout {
+
+    private static final Integer MAX_RETRIES = 3;
+    private static final Set<Integer> RETRYABLE_CODES = new Set<Integer>{
+        408, 429, 500, 502, 503, 504
+    };
+
+    public static HttpResponse callWithRetry(HttpRequest request) {
+        Integer attempts = 0;
+
+        while (attempts < MAX_RETRIES) {
+            HttpResponse res = new Http().send(request);
+
+            if (!RETRYABLE_CODES.contains(res.getStatusCode())) {
+                return res;
+            }
+
+            attempts++;
+            System.debug('Retry ' + attempts + ' for ' + res.getStatusCode());
+        }
+
+        throw new CalloutException('Max retries exceeded');
+    }
+}
+```
+
+## Queueable Pattern (Async)
+
+```apex
+public class AsyncCallout implements Queueable, Database.AllowsCallouts {
+
+    private Id recordId;
+
+    public AsyncCallout(Id recordId) {
+        this.recordId = recordId;
+    }
+
+    public void execute(QueueableContext context) {
+        // Query record
+        Account acc = [SELECT Id, Name FROM Account WHERE Id = :recordId];
+
+        // Make callout
+        HttpRequest req = new HttpRequest();
+        req.setEndpoint('callout:MyAPI/accounts');
+        req.setMethod('POST');
+        req.setBody(JSON.serialize(new Map<String, Object>{
+            'name' => acc.Name,
+            'sfId' => acc.Id
+        }));
+
+        HttpResponse res = new Http().send(req);
+
+        // Update record with result
+        if (res.getStatusCode() == 201) {
+            acc.External_Id__c = extractId(res.getBody());
+            update acc;
+        }
+    }
+
+    private String extractId(String body) {
+        Map<String, Object> result = (Map<String, Object>) JSON.deserializeUntyped(body);
+        return (String) result.get('id');
+    }
+}
+
+// Usage from trigger:
+// System.enqueueJob(new AsyncCallout(accountId));
+```
+
+## Pagination Pattern
+
+```apex
+public class PaginatedApiClient {
+
+    public static List<Map<String, Object>> getAllRecords(String endpoint) {
+        List<Map<String, Object>> allRecords = new List<Map<String, Object>>();
+        String nextPageUrl = endpoint;
+
+        while (String.isNotBlank(nextPageUrl)) {
+            HttpResponse res = makeRequest('GET', nextPageUrl, null);
+            Map<String, Object> response = (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
+
+            // Add records from this page
+            List<Object> records = (List<Object>) response.get('data');
+            for (Object rec : records) {
+                allRecords.add((Map<String, Object>) rec);
+            }
+
+            // Get next page URL
+            nextPageUrl = (String) response.get('nextPage');
+        }
+
+        return allRecords;
+    }
+}
+```
+
+## Governor Limits
+
+| Limit | Value |
+|-------|-------|
+| Callouts per transaction | 100 |
+| Maximum timeout | 120,000 ms (120 seconds) |
+| Maximum request size | 6 MB |
+| Maximum response size | 6 MB |
+| Concurrent long-running requests | 10 |
+
+## Testing Callouts
+
+```apex
+@isTest
+private class ApiClientTest {
+
+    @isTest
+    static void testSuccessfulCallout() {
+        // Set mock
+        Test.setMock(HttpCalloutMock.class, new MockSuccess());
+
+        Test.startTest();
+        Map<String, Object> result = ApiClient.callApi('/endpoint');
+        Test.stopTest();
+
+        System.assertEquals('value', result.get('key'));
+    }
+
+    private class MockSuccess implements HttpCalloutMock {
+        public HttpResponse respond(HttpRequest req) {
+            HttpResponse res = new HttpResponse();
+            res.setStatusCode(200);
+            res.setBody('{"key": "value"}');
+            return res;
+        }
+    }
+}
+```
+
+## Best Practices
+
+1. **Always use Named Credentials** - Never hardcode endpoints or credentials
+2. **Set appropriate timeouts** - Default may be too short for slow APIs
+3. **Handle all error cases** - Don't assume success
+4. **Log requests and responses** - Essential for debugging
+5. **Use async for trigger contexts** - Queueable with AllowsCallouts
+6. **Implement retry logic** - For transient failures
+7. **Monitor governor limits** - Especially callout count
+8. **Parse errors gracefully** - APIs return errors in various formats

package/skills/building-sf-integrations/references/scoring-rubric.md

@@ -0,0 +1,59 @@
+<!-- Parent: building-sf-integrations/SKILL.md -->
+
+# Scoring System (120 Points)
+
+## Category Breakdown
+
+| Category | Points | Evaluation Criteria |
+|----------|--------|---------------------|
+| **Security** | 30 | Named Credentials used (no hardcoded secrets), OAuth scopes minimized, certificate auth where applicable |
+| **Error Handling** | 25 | Retry logic present, timeout handling (120s max), specific exception types, logging implemented |
+| **Bulkification** | 20 | Batch callouts considered, CDC bulk handling, event batching for Platform Events |
+| **Architecture** | 20 | Async patterns for DML-triggered callouts, proper service layer separation, single responsibility |
+| **Best Practices** | 15 | Governor limit awareness, proper HTTP methods, idempotency for retries |
+| **Documentation** | 10 | Clear intent documented, endpoint versioning noted, API contract documented |
+
+## Scoring Thresholds
+
+| Rating | Score Range | Description |
+|--------|------------|-------------|
+| Excellent | 108-120 | Production-ready, follows all best practices |
+| Very Good | 90-107 | Minor improvements suggested |
+| Good | 72-89 | Acceptable with noted improvements |
+| Needs Work | 54-71 | Address issues before deployment |
+| Block | <54 | CRITICAL issues, do not deploy |
+
+## Scoring Output Format
+
+```
+📊 INTEGRATION SCORE: XX/120 ⭐⭐⭐⭐ Rating
+════════════════════════════════════════════════════
+
+🔐 Security           XX/30  ████████░░ XX%
+├─ Named Credentials used: ✅
+├─ No hardcoded secrets: ✅
+└─ OAuth scopes minimal: ✅
+
+⚠️ Error Handling     XX/25  ████████░░ XX%
+├─ Retry logic: ✅
+├─ Timeout handling: ✅
+└─ Logging: ✅
+
+📦 Bulkification      XX/20  ████████░░ XX%
+├─ Batch callouts: ✅
+└─ Event batching: ✅
+
+🏗️ Architecture       XX/20  ████████░░ XX%
+├─ Async patterns: ✅
+└─ Service separation: ✅
+
+✅ Best Practices     XX/15  ████████░░ XX%
+├─ Governor limits: ✅
+└─ Idempotency: ✅
+
+📝 Documentation      XX/10  ████████░░ XX%
+├─ Clear intent: ✅
+└─ API versioning: ✅
+
+════════════════════════════════════════════════════
+```

package/skills/building-sf-integrations/references/security-best-practices.md

@@ -0,0 +1,248 @@
+<!-- Parent: building-sf-integrations/SKILL.md -->
+# Integration Security Best Practices
+
+## Overview
+
+Security is critical for integrations. This guide covers best practices for securing Salesforce integrations with external systems.
+
+## Credential Management
+
+### DO: Use Named Credentials
+
+```apex
+// ✅ CORRECT - Named Credential handles auth
+HttpRequest req = new HttpRequest();
+req.setEndpoint('callout:MySecureAPI/resource');
+```
+
+### DON'T: Hardcode Credentials
+
+```apex
+// ❌ WRONG - Never hardcode credentials
+req.setHeader('Authorization', 'Bearer sk_live_abc123...');
+req.setEndpoint('https://api.example.com');
+```
+
+### Credential Storage Rules
+
+| Item | Storage Location | Never Store In |
+|------|------------------|----------------|
+| API Keys | Named Credential | Apex code, Custom Settings |
+| Client Secrets | Named Credential / External Credential | Source control |
+| Certificates | Certificate & Key Management | Static Resources |
+| Passwords | Named Credential | Custom Metadata |
+
+## OAuth Best Practices
+
+### Scope Minimization
+
+Request only necessary scopes:
+
+```
+✅ read:orders write:orders
+❌ admin:* read:* write:*
+```
+
+### Token Handling
+
+- Never log access tokens
+- Don't expose tokens in error messages
+- Use short-lived tokens when possible
+- Implement token refresh handling
+
+### PKCE for Public Clients
+
+For mobile or SPA clients:
+
+```
+Use Authorization Code with PKCE, not Implicit flow
+```
+
+## Network Security
+
+### Remote Site Settings
+
+- Only allow necessary domains
+- Don't use wildcard domains
+- Review and audit regularly
+
+### Certificate Validation
+
+- Use trusted CA certificates
+- Don't disable SSL/TLS verification
+- Monitor certificate expiration
+
+### IP Restrictions
+
+For Connected Apps:
+- Configure IP relaxation carefully
+- Use "Enforce IP restrictions" when possible
+
+## Input Validation
+
+### Validate External Data
+
+```apex
+// Validate before processing
+public static void processExternalData(String externalId) {
+    // Validate format
+    if (!Pattern.matches('[A-Za-z0-9]{10,20}', externalId)) {
+        throw new ValidationException('Invalid external ID format');
+    }
+
+    // Sanitize for SOQL
+    String safeId = String.escapeSingleQuotes(externalId);
+}
+```
+
+### Output Encoding
+
+```apex
+// Encode data sent to external systems
+String encodedData = EncodingUtil.urlEncode(userData, 'UTF-8');
+```
+
+## Error Handling Security
+
+### Don't Expose Internal Details
+
+```apex
+// ❌ WRONG - Exposes internal structure
+throw new CalloutException('Failed: ' + response.getBody());
+
+// ✅ CORRECT - User-friendly, log details separately
+System.debug(LoggingLevel.ERROR, 'API Error: ' + response.getBody());
+throw new CalloutException('Unable to complete request. Contact support.');
+```
+
+### Log Securely
+
+```apex
+// ❌ WRONG - Logs sensitive data
+System.debug('Request: ' + JSON.serialize(request)); // May contain PII
+
+// ✅ CORRECT - Redact sensitive fields
+System.debug('Request to: ' + endpoint + ', Status: ' + statusCode);
+```
+
+## API Security Patterns
+
+### Rate Limiting Awareness
+
+```apex
+if (response.getStatusCode() == 429) {
+    String retryAfter = response.getHeader('Retry-After');
+    // Implement backoff, don't hammer the API
+}
+```
+
+### Idempotency Keys
+
+For POST requests that shouldn't duplicate:
+
+```apex
+req.setHeader('Idempotency-Key', generateUniqueKey());
+```
+
+### Request Signing
+
+For APIs requiring signature:
+
+```apex
+String signature = generateHmacSignature(payload, secretKey);
+req.setHeader('X-Signature', signature);
+```
+
+## User Context Security
+
+### Per-User vs Named Principal
+
+| Scenario | Use |
+|----------|-----|
+| User-specific data access | Per-User Principal |
+| Background/batch jobs | Named Principal |
+| Service integrations | Named Principal |
+| User-initiated with audit | Per-User Principal |
+
+### Audit Logging
+
+```apex
+public static void logIntegrationActivity(String operation, Id userId, String externalSystem) {
+    Integration_Log__c log = new Integration_Log__c(
+        Operation__c = operation,
+        User__c = userId,
+        External_System__c = externalSystem,
+        Timestamp__c = Datetime.now()
+    );
+    insert log;
+}
+```
+
+## Platform Event Security
+
+### Sensitive Data in Events
+
+- Don't include PII in event payloads when avoidable
+- Use record IDs and query for details
+- Consider encryption for sensitive fields
+
+### Event Consumer Validation
+
+```apex
+trigger SecureEventHandler on My_Event__e (after insert) {
+    for (My_Event__e event : Trigger.new) {
+        // Validate event source/origin if possible
+        if (!isValidEventSource(event)) {
+            System.debug(LoggingLevel.WARN, 'Suspicious event: ' + event.ReplayId);
+            continue;
+        }
+        processEvent(event);
+    }
+}
+```
+
+## Security Checklist
+
+### Before Deployment
+
+- [ ] Named Credentials used for all external calls
+- [ ] No hardcoded credentials in code
+- [ ] OAuth scopes minimized
+- [ ] Remote Site Settings restricted
+- [ ] Error messages don't expose internals
+- [ ] Sensitive data not logged
+- [ ] Input validation implemented
+- [ ] Rate limiting handled
+- [ ] Certificate expiration monitored
+
+### Regular Review
+
+- [ ] Audit Named Credential usage
+- [ ] Review integration user permissions
+- [ ] Check for unused credentials
+- [ ] Monitor integration error logs
+- [ ] Validate certificate validity
+- [ ] Review OAuth app authorizations
+
+## Compliance Considerations
+
+### GDPR / Data Privacy
+
+- Minimize data transferred
+- Document data flows
+- Implement data deletion for integrated records
+- Encrypt PII in transit and at rest
+
+### SOC 2 / Security Audits
+
+- Maintain integration documentation
+- Log all external access
+- Implement change management
+- Regular security assessments
+
+### HIPAA (Healthcare)
+
+- Business Associate Agreements
+- Encryption requirements
+- Access logging
+- Minimum necessary standard

package/skills/building-sf-integrations/scripts/README.md

@@ -0,0 +1,100 @@
+# building-sf-integrations Helper Scripts
+
+Automation scripts for configuring Salesforce integrations without manual UI steps.
+
+> **Mirror note:** These files mirror the canonical generic helpers in the repository root `scripts/` directory. Keep both locations aligned until the packaging layout is consolidated.
+
+## Scripts
+
+| Script | Purpose | Auth Type |
+|--------|---------|-----------|
+| `configure-named-credential.sh` | Set API keys via ConnectApi | Enhanced Named Credentials |
+| `set-api-credential.sh` | Store keys in Custom Settings | Legacy (dev/test) |
+
+## Quick Start
+
+```bash
+# Enhanced Named Credentials (recommended for production)
+./configure-named-credential.sh <external-credential-name> <principal-name> <org-alias>
+
+# Custom Settings (legacy, for dev/test)
+./set-api-credential.sh <setting-name> - <org-alias>
+```
+
+## Prerequisites
+
+- **Salesforce CLI v2+** (`sf` command)
+- **Authenticated org** (`sf org login web -a <alias>`)
+- **Deployed metadata** (External Credential, Named Credential, CSP)
+
+## Usage Examples
+
+### Configure Named Credential
+
+```bash
+# Interactive mode - prompts for API key securely
+./configure-named-credential.sh VisualCrossingWeather weatherAPIKey MyDevOrg
+
+# The script will:
+# 1. Validate org connection
+# 2. Check External Credential exists
+# 3. Prompt for API key (hidden input)
+# 4. Execute ConnectApi Apex to store encrypted
+```
+
+### Custom Settings (Legacy)
+
+```bash
+# Secure input (dash prompts for hidden input)
+./set-api-credential.sh WeatherAPI - MyDevOrg
+
+# Direct input (less secure, for CI/CD)
+./set-api-credential.sh WeatherAPI sk_live_abc123 MyDevOrg
+```
+
+## Templates
+
+The `templates/` directory contains customizable scripts for new integrations:
+
+| Template | Purpose |
+|----------|---------|
+| `setup-credentials-with-csp.sh` | Full setup with CSP Trusted Sites |
+
+### Using Templates
+
+```bash
+# Copy template for your integration
+cp templates/setup-credentials-with-csp.sh my-integration-setup.sh
+
+# Edit configuration variables
+# - SKILL_NAME
+# - CSP_NAME
+# - API_KEY_URL
+```
+
+## Auto-Run Behavior
+
+When you create credential metadata files, Claude will automatically suggest running these scripts:
+
+| File Pattern | Suggested Script |
+|--------------|------------------|
+| `*.namedCredential-meta.xml` | `configure-named-credential.sh` |
+| `*.externalCredential-meta.xml` | `configure-named-credential.sh` |
+
+## Troubleshooting
+
+**"sf: command not found"**
+- Install Salesforce CLI: `npm install -g @salesforce/cli`
+
+**"Not authenticated"**
+- Run: `sf org login web -a <alias>`
+
+**"External Credential not found"**
+- Deploy External Credential first
+- Check developer name matches
+
+## Related Documentation
+
+- [Named Credentials Automation Guide](../references/named-credentials-automation.md)
+- [Named Credentials Template Reference](../references/named-credentials-guide.md)
+- [Security Best Practices](../references/security-best-practices.md)