@salesforce/afv-skills 1.20.0 → 1.22.0

package/skills/integration-connectivity-generate/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: integration-connectivity-generate
+description: "Salesforce integration architecture and runtime plumbing with 120-point scoring. Use this skill to set up Named Credentials, External Credentials, External Services, REST/SOAP callout patterns, Platform Events, and Change Data Capture. TRIGGER when: user sets up Named Credentials, External Services, REST/SOAP callouts, Platform Events, CDC, or touches .namedCredential-meta.xml files. DO NOT TRIGGER when: Connected App/OAuth config (use integration-connectivity-connected-app-configure), Apex-only logic (use platform-apex-generate), data import/export (use platform-data-manage), or CDC channel-membership metadata such as PlatformEventChannel, PlatformEventChannelMember, or EnrichedField (use integration-eventing-cdc-configure)."
+metadata:
+  version: "1.1"
+---
+
+# integration-connectivity-generate: Salesforce Integration Patterns Expert
+
+Use this skill when the user needs **integration architecture and runtime plumbing**: Named Credentials, External Credentials, External Services, REST/SOAP callout patterns, Platform Events, CDC, and event-driven integration design.
+
+## When This Skill Owns the Task
+
+Use `integration-connectivity-generate` when the work involves:
+- `.namedCredential-meta.xml` or External Credential metadata
+- outbound REST/SOAP callouts
+- External Service registration from OpenAPI specs
+- Platform Events, CDC, and event-driven architecture
+- choosing sync vs async integration patterns
+
+Delegate elsewhere when the user is:
+- configuring the OAuth app itself → [integration-connectivity-connected-app-configure](../integration-connectivity-connected-app-configure/SKILL.md)
+- writing Apex-only business logic → [platform-apex-generate](../platform-apex-generate/SKILL.md)
+- deploying metadata → [platform-metadata-deploy](../platform-metadata-deploy/SKILL.md)
+- importing/exporting data → [platform-data-manage](../platform-data-manage/SKILL.md)
+
+---
+
+## Required Context to Gather First
+
+Ask for or infer:
+- integration style: outbound callout, inbound event, External Service, CDC, platform event
+- auth method
+- sync vs async requirement
+- system endpoint / spec details
+- rate limits, retry expectations, and failure tolerance
+- whether this is net-new design or repair of an existing integration
+
+---
+
+## Recommended Workflow
+
+### 1. Choose the integration pattern
+| Need | Default pattern |
+|---|---|
+| authenticated outbound API call | Named Credential / External Credential + Apex or Flow |
+| spec-driven API client | External Service |
+| trigger-originated callout | async callout pattern |
+| decoupled event publishing | Platform Events |
+| change-stream consumption | CDC |
+
+### 2. Choose the auth model
+Prefer secure runtime-managed auth:
+- Named Credentials / External Credentials
+- OAuth or JWT via the right credential model
+- no hardcoded secrets in code
+
+### 3. Generate from the right templates
+Use the provided assets under:
+- `assets/named-credentials/`
+- `assets/external-credentials/`
+- `assets/external-services/`
+- `assets/callouts/`
+- `assets/platform-events/`
+- `assets/cdc/`
+- `assets/soap/`
+
+### 4. Validate operational safety
+Check:
+- timeout and retry handling
+- async strategy for trigger-originated work
+- logging / observability
+- event retention and subscriber implications
+
+### 5. Hand off deployment or implementation details
+Use:
+- [platform-metadata-deploy](../platform-metadata-deploy/SKILL.md) for deployment
+- [platform-apex-generate](../platform-apex-generate/SKILL.md) for deeper service / retry code
+- [automation-flow-generate](../automation-flow-generate/SKILL.md) for declarative HTTP callout orchestration
+
+---
+
+## High-Signal Rules
+
+- never hardcode credentials
+- do not do synchronous callouts from triggers
+- define timeout behavior explicitly
+- plan retries for transient failures
+- use middleware / event-driven patterns when outbound volume is high
+- prefer External Credentials architecture for new development when supported
+
+Common anti-patterns:
+- sync trigger callouts
+- no retry or dead-letter strategy
+- no request/response logging
+- mixing auth setup responsibilities with runtime integration design
+
+---
+
+## Output Format
+
+When finishing, report in this order:
+1. **Integration pattern chosen**
+2. **Auth model chosen**
+3. **Files created or updated**
+4. **Operational safeguards**
+5. **Deployment / testing next step**
+
+Suggested shape:
+
+```text
+Integration: <summary>
+Pattern: <named credential / external service / event / cdc / callout>
+Files: <paths>
+Safety: <timeouts, retries, async, logging>
+Next step: <deploy, register, test, or implement>
+```
+
+---
+
+## Cross-Skill Integration
+
+| Need | Delegate to | Reason |
+|---|---|---|
+| OAuth app setup | [integration-connectivity-connected-app-configure](../integration-connectivity-connected-app-configure/SKILL.md) | consumer key / cert / app config |
+| advanced callout service code | [platform-apex-generate](../platform-apex-generate/SKILL.md) | Apex implementation |
+| declarative HTTP callout / Flow wrapper | [automation-flow-generate](../automation-flow-generate/SKILL.md) | Flow orchestration |
+| deploy integration metadata | [platform-metadata-deploy](../platform-metadata-deploy/SKILL.md) | validation and rollout |
+| use integration from Agentforce | [agentforce-generate](../agentforce-generate/SKILL.md) | agent action composition |
+
+---
+
+## Reference Map
+
+### Start here
+- [references/named-credentials-guide.md](references/named-credentials-guide.md)
+- [references/external-services-guide.md](references/external-services-guide.md)
+- [references/callout-patterns.md](references/callout-patterns.md)
+- [references/rest-callout-patterns.md](references/rest-callout-patterns.md)
+- [references/security-best-practices.md](references/security-best-practices.md)
+
+### Event-driven / platform patterns
+- [references/event-patterns.md](references/event-patterns.md)
+- [references/platform-events-guide.md](references/platform-events-guide.md)
+- [references/cdc-guide.md](references/cdc-guide.md)
+- [references/event-driven-architecture-guide.md](references/event-driven-architecture-guide.md)
+- [references/messaging-api-v2.md](references/messaging-api-v2.md)
+
+### CLI / automation / scoring
+- [references/cli-reference.md](references/cli-reference.md)
+- [references/named-credentials-automation.md](references/named-credentials-automation.md)
+- [references/scoring-rubric.md](references/scoring-rubric.md)
+- [scripts/README.md](scripts/README.md) — automation scripts overview (configure-named-credential.sh, set-api-credential.sh)
+
+### Asset templates
+- `assets/named-credentials/` — Named Credential XML templates (OAuth, JWT, Certificate, Custom auth)
+- `assets/external-credentials/` — External Credential XML templates (OAuth, JWT)
+- `assets/external-services/` — External Service registration template and operations guide
+- `assets/callouts/` — REST sync, Queueable, retry handler, and HTTP response handler Apex templates
+- `assets/platform-events/` — Platform Event definition, publisher, and subscriber templates
+- `assets/cdc/` — CDC handler and subscriber trigger templates
+- `assets/soap/` — SOAP callout service template and wsdl2apex guide
+- `assets/endpoint-security/` — Remote Site Setting and CSP Trusted Site XML templates
+
+### Automation hooks
+- `hooks/scripts/suggest_credential_setup.py` — auto-suggests credential configuration steps when integration files are detected
+- `hooks/scripts/validate_integration.py` — validates integration patterns before agent responses
+
+---
+
+## Output Expectations
+
+When this skill completes an integration task, it produces:
+
+1. **Credential metadata** — one or more files in `assets/named-credentials/` or `assets/external-credentials/` filled with org-specific values
+2. **Callout Apex class** — a `.cls` file using the Named Credential pattern, with async/sync pattern chosen based on context
+3. **Event/CDC artifacts** — Platform Event `.object-meta.xml`, subscriber trigger, or CDC config (when event-driven pattern is chosen)
+4. **Endpoint security metadata** — Remote Site Setting and/or CSP Trusted Site XML files
+5. **Scoring report** — 120-point score across 6 categories (Security, Error Handling, Bulkification, Architecture, Best Practices, Documentation)
+6. **Next step** — a deployment or testing instruction for the generated artifacts
+
+---
+
+## Score Guide
+
+| Score | Meaning |
+|---|---|
+| 108+ | strong production-ready integration design |
+| 90–107 | good design with some hardening left |
+| 72–89 | workable but needs architectural review |
+| < 72 | unsafe / incomplete for deployment |

package/skills/integration-connectivity-generate/assets/callouts/callout-retry-handler.cls

@@ -0,0 +1,167 @@
+/**
+ * @description Retry Handler with Exponential Backoff for HTTP Callouts
+ *
+ * Use Case: Handle transient failures with intelligent retry
+ * - Network timeouts
+ * - 5xx server errors
+ * - Rate limiting (429)
+ *
+ * Features:
+ * - Exponential backoff between retries
+ * - Configurable retry count
+ * - Jitter to prevent thundering herd
+ * - Distinguishes retryable vs non-retryable errors
+ *
+ * IMPORTANT: Apex doesn't have Thread.sleep(), so retry with backoff
+ *            is implemented via Queueable job scheduling for async contexts.
+ *            For sync contexts, this provides immediate retry without delay.
+ *
+ * @author {{Author}}
+ * @date {{Date}}
+ */
+public with sharing class CalloutRetryHandler {
+
+    // Configuration
+    private static final Integer MAX_RETRIES = 3;
+    private static final Integer BASE_DELAY_MS = 1000; // 1 second
+    private static final Integer MAX_DELAY_MS = 30000; // 30 seconds
+
+    // Retryable status codes
+    private static final Set<Integer> RETRYABLE_STATUS_CODES = new Set<Integer>{
+        408, // Request Timeout
+        429, // Too Many Requests (Rate Limited)
+        500, // Internal Server Error
+        502, // Bad Gateway
+        503, // Service Unavailable
+        504  // Gateway Timeout
+    };
+
+    /**
+     * @description Execute HTTP request with retry logic (immediate retries)
+     * @param request HttpRequest to execute
+     * @return HttpResponse from successful call
+     * @throws CalloutException if all retries exhausted
+     */
+    public static HttpResponse executeWithRetry(HttpRequest request) {
+        return executeWithRetry(request, MAX_RETRIES);
+    }
+
+    /**
+     * @description Execute HTTP request with configurable retry count
+     * @param request HttpRequest to execute
+     * @param maxRetries Maximum retry attempts
+     * @return HttpResponse from successful call
+     * @throws CalloutException if all retries exhausted
+     */
+    public static HttpResponse executeWithRetry(HttpRequest request, Integer maxRetries) {
+        Integer retryCount = 0;
+        HttpResponse response;
+        Exception lastException;
+
+        while (retryCount <= maxRetries) {
+            try {
+                Http http = new Http();
+                response = http.send(request);
+
+                Integer statusCode = response.getStatusCode();
+
+                // Success - return immediately
+                if (statusCode >= 200 && statusCode < 300) {
+                    return response;
+                }
+
+                // Client error (4xx except 408, 429) - don't retry
+                if (statusCode >= 400 && statusCode < 500 &&
+                    !RETRYABLE_STATUS_CODES.contains(statusCode)) {
+                    throw new NonRetryableException(
+                        'Client Error (' + statusCode + '): ' + response.getBody()
+                    );
+                }
+
+                // Retryable error - check if we should retry
+                if (RETRYABLE_STATUS_CODES.contains(statusCode)) {
+                    retryCount++;
+                    if (retryCount > maxRetries) {
+                        throw new RetryExhaustedException(
+                            'Max retries exhausted. Last status: ' + statusCode +
+                            ', Body: ' + response.getBody()
+                        );
+                    }
+
+                    // Log retry attempt
+                    System.debug(LoggingLevel.WARN,
+                        'Retryable error (' + statusCode + '). Attempt ' + retryCount +
+                        ' of ' + maxRetries);
+
+                    // For 429, check Retry-After header
+                    if (statusCode == 429) {
+                        String retryAfter = response.getHeader('Retry-After');
+                        if (String.isNotBlank(retryAfter)) {
+                            System.debug(LoggingLevel.WARN, 'Rate limited. Retry-After: ' + retryAfter);
+                        }
+                    }
+
+                    // Continue to next retry (no delay in sync Apex)
+                    continue;
+                }
+
+                // Other status codes - don't retry
+                return response;
+
+            } catch (CalloutException e) {
+                // Network/connection error
+                lastException = e;
+                retryCount++;
+
+                if (retryCount > maxRetries) {
+                    throw new RetryExhaustedException(
+                        'Max retries exhausted after CalloutException: ' + e.getMessage()
+                    );
+                }
+
+                System.debug(LoggingLevel.WARN,
+                    'CalloutException on attempt ' + retryCount + ': ' + e.getMessage());
+            }
+        }
+
+        // Should not reach here, but handle edge case
+        throw new RetryExhaustedException('Unexpected retry loop exit');
+    }
+
+    /**
+     * @description Calculate delay with exponential backoff and jitter
+     *              (Useful for scheduled retry jobs)
+     * @param retryAttempt Current retry attempt (1-based)
+     * @return Delay in milliseconds
+     */
+    public static Integer calculateBackoffDelay(Integer retryAttempt) {
+        // Exponential backoff: baseDelay * 2^(attempt-1)
+        Integer exponentialDelay = BASE_DELAY_MS * (Integer) Math.pow(2, retryAttempt - 1);
+
+        // Add jitter (random 0-25% of delay)
+        Double jitter = Math.random() * 0.25 * exponentialDelay;
+        Integer delayWithJitter = exponentialDelay + (Integer) jitter;
+
+        // Cap at max delay
+        return Math.min(delayWithJitter, MAX_DELAY_MS);
+    }
+
+    /**
+     * @description Check if HTTP status code is retryable
+     * @param statusCode HTTP status code
+     * @return True if request should be retried
+     */
+    public static Boolean isRetryable(Integer statusCode) {
+        return RETRYABLE_STATUS_CODES.contains(statusCode);
+    }
+
+    /**
+     * @description Exception for non-retryable errors (4xx client errors)
+     */
+    public class NonRetryableException extends Exception {}
+
+    /**
+     * @description Exception when all retry attempts exhausted
+     */
+    public class RetryExhaustedException extends Exception {}
+}

package/skills/integration-connectivity-generate/assets/callouts/http-response-handler.cls

@@ -0,0 +1,257 @@
+/**
+ * @description HTTP Response Handler Utility
+ *
+ * Use Case: Standardized response parsing and error handling
+ * - Parse JSON responses to typed objects
+ * - Handle different content types
+ * - Extract error messages from various API formats
+ * - Logging for debugging
+ *
+ * @author {{Author}}
+ * @date {{Date}}
+ */
+public with sharing class HttpResponseHandler {
+
+    /**
+     * @description Parse HTTP response to Map
+     * @param response HttpResponse to parse
+     * @return Parsed response as Map<String, Object>
+     * @throws HttpResponseException for error status codes
+     */
+    public static Map<String, Object> parseJsonResponse(HttpResponse response) {
+        validateSuccessResponse(response);
+
+        String body = response.getBody();
+        if (String.isBlank(body) || response.getStatusCode() == 204) {
+            return new Map<String, Object>();
+        }
+
+        try {
+            return (Map<String, Object>) JSON.deserializeUntyped(body);
+        } catch (JSONException e) {
+            throw new HttpResponseException(
+                'Failed to parse JSON response: ' + e.getMessage() +
+                '. Body: ' + body.left(500)
+            );
+        }
+    }
+
+    /**
+     * @description Parse HTTP response to List
+     * @param response HttpResponse to parse
+     * @return Parsed response as List<Object>
+     * @throws HttpResponseException for error status codes
+     */
+    public static List<Object> parseJsonArrayResponse(HttpResponse response) {
+        validateSuccessResponse(response);
+
+        String body = response.getBody();
+        if (String.isBlank(body)) {
+            return new List<Object>();
+        }
+
+        try {
+            return (List<Object>) JSON.deserializeUntyped(body);
+        } catch (JSONException e) {
+            throw new HttpResponseException(
+                'Failed to parse JSON array response: ' + e.getMessage()
+            );
+        }
+    }
+
+    /**
+     * @description Parse HTTP response to specific type
+     * @param response HttpResponse to parse
+     * @param targetType Apex type to deserialize to
+     * @return Deserialized object
+     * @throws HttpResponseException for error status codes
+     */
+    public static Object parseTypedResponse(HttpResponse response, Type targetType) {
+        validateSuccessResponse(response);
+
+        String body = response.getBody();
+        if (String.isBlank(body)) {
+            return null;
+        }
+
+        try {
+            return JSON.deserialize(body, targetType);
+        } catch (JSONException e) {
+            throw new HttpResponseException(
+                'Failed to deserialize response to ' + targetType.getName() + ': ' + e.getMessage()
+            );
+        }
+    }
+
+    /**
+     * @description Validate response is successful (2xx)
+     * @param response HttpResponse to validate
+     * @throws HttpResponseException for non-2xx status codes
+     */
+    public static void validateSuccessResponse(HttpResponse response) {
+        Integer statusCode = response.getStatusCode();
+
+        // Log response for debugging
+        logResponse(response);
+
+        if (statusCode >= 200 && statusCode < 300) {
+            return; // Success
+        }
+
+        String errorMessage = extractErrorMessage(response);
+
+        if (statusCode >= 400 && statusCode < 500) {
+            throw new ClientErrorException(
+                'HTTP ' + statusCode + ': ' + errorMessage
+            );
+        }
+
+        if (statusCode >= 500) {
+            throw new ServerErrorException(
+                'HTTP ' + statusCode + ': ' + errorMessage
+            );
+        }
+
+        throw new HttpResponseException(
+            'Unexpected HTTP status ' + statusCode + ': ' + errorMessage
+        );
+    }
+
+    /**
+     * @description Extract error message from response body
+     * @param response HttpResponse containing error
+     * @return Error message string
+     */
+    public static String extractErrorMessage(HttpResponse response) {
+        String body = response.getBody();
+
+        if (String.isBlank(body)) {
+            return 'No response body';
+        }
+
+        // Try to parse as JSON error
+        try {
+            Map<String, Object> errorObj = (Map<String, Object>) JSON.deserializeUntyped(body);
+
+            // Common error formats
+            // Format 1: { "error": "message" }
+            if (errorObj.containsKey('error')) {
+                Object error = errorObj.get('error');
+                if (error instanceof String) {
+                    return (String) error;
+                }
+                if (error instanceof Map<String, Object>) {
+                    Map<String, Object> errorMap = (Map<String, Object>) error;
+                    if (errorMap.containsKey('message')) {
+                        return (String) errorMap.get('message');
+                    }
+                }
+            }
+
+            // Format 2: { "message": "error message" }
+            if (errorObj.containsKey('message')) {
+                return (String) errorObj.get('message');
+            }
+
+            // Format 3: { "errors": [{ "message": "..." }] }
+            if (errorObj.containsKey('errors')) {
+                Object errors = errorObj.get('errors');
+                if (errors instanceof List<Object>) {
+                    List<Object> errorList = (List<Object>) errors;
+                    if (!errorList.isEmpty()) {
+                        Object firstError = errorList[0];
+                        if (firstError instanceof Map<String, Object>) {
+                            Map<String, Object> errMap = (Map<String, Object>) firstError;
+                            if (errMap.containsKey('message')) {
+                                return (String) errMap.get('message');
+                            }
+                        }
+                        if (firstError instanceof String) {
+                            return (String) firstError;
+                        }
+                    }
+                }
+            }
+
+            // Format 4: { "detail": "error detail" }
+            if (errorObj.containsKey('detail')) {
+                return (String) errorObj.get('detail');
+            }
+
+            // Fallback: return serialized error object
+            return JSON.serialize(errorObj);
+
+        } catch (Exception e) {
+            // Not JSON - return raw body (truncated)
+            return body.left(1000);
+        }
+    }
+
+    /**
+     * @description Log HTTP response for debugging
+     * @param response HttpResponse to log
+     */
+    private static void logResponse(HttpResponse response) {
+        System.debug(LoggingLevel.DEBUG, '=== HTTP Response ===');
+        System.debug(LoggingLevel.DEBUG, 'Status: ' + response.getStatusCode() + ' ' + response.getStatus());
+
+        // Log important headers
+        String[] headerKeys = new String[]{ 'Content-Type', 'X-Request-Id', 'Retry-After', 'X-RateLimit-Remaining' };
+        for (String key : headerKeys) {
+            String value = response.getHeader(key);
+            if (String.isNotBlank(value)) {
+                System.debug(LoggingLevel.DEBUG, key + ': ' + value);
+            }
+        }
+
+        // Log body (truncated for large responses)
+        String body = response.getBody();
+        if (String.isNotBlank(body)) {
+            System.debug(LoggingLevel.DEBUG, 'Body: ' + body.left(5000));
+        }
+    }
+
+    /**
+     * @description Get response header value
+     * @param response HttpResponse
+     * @param headerName Header name to retrieve
+     * @return Header value or null
+     */
+    public static String getHeader(HttpResponse response, String headerName) {
+        return response.getHeader(headerName);
+    }
+
+    /**
+     * @description Check if response indicates success
+     * @param response HttpResponse to check
+     * @return True if status code is 2xx
+     */
+    public static Boolean isSuccess(HttpResponse response) {
+        Integer statusCode = response.getStatusCode();
+        return statusCode >= 200 && statusCode < 300;
+    }
+
+    /**
+     * @description Check if response indicates rate limiting
+     * @param response HttpResponse to check
+     * @return True if status code is 429
+     */
+    public static Boolean isRateLimited(HttpResponse response) {
+        return response.getStatusCode() == 429;
+    }
+
+    /**
+     * @description Base exception for HTTP response errors
+     */
+    public virtual class HttpResponseException extends Exception {}
+
+    /**
+     * @description Exception for 4xx client errors
+     */
+    public class ClientErrorException extends HttpResponseException {}
+
+    /**
+     * @description Exception for 5xx server errors
+     */
+    public class ServerErrorException extends HttpResponseException {}
+}