@salesforce/afv-skills 1.22.0 → 1.23.0

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

@@ -1,288 +0,0 @@
-<!-- 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

@@ -1,59 +0,0 @@
-<!-- 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

@@ -1,248 +0,0 @@
-<!-- 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

@@ -1,100 +0,0 @@
-# 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)