@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/building-omnistudio-omniscript/scripts/check-duplicate-omniscript.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+# Verify no duplicate Type/SubType/Language exists before creating a new OmniScript.
+# Usage: ./check-duplicate-omniscript.sh <Type> <SubType> <Language> <org>
+# Example: ./check-duplicate-omniscript.sh ServiceRequest NewCase English myOrg
+
+TYPE="${1:?Usage: $0 <Type> <SubType> <Language> <org>}"
+SUBTYPE="${2:?}"
+LANGUAGE="${3:?}"
+ORG="${4:?}"
+
+sf data query \
+  -q "SELECT Id,Name,Type,SubType,Language,IsActive,VersionNumber FROM OmniProcess WHERE Type='${TYPE}' AND SubType='${SUBTYPE}' AND Language='${LANGUAGE}' AND OmniProcessType='OmniScript' LIMIT 10" \
+  -o "${ORG}"

package/skills/building-omnistudio-omniscript/scripts/cli-reference.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# OmniScript CLI command reference. Not meant to be run directly.
+# Copy individual commands as needed. Replace <org>, <id>, <Type>, <SubType>, <Name> with actual values.
+
+# List active OmniScripts
+sf data query -q "SELECT Id,Name,Type,SubType,Language,IsActive,VersionNumber FROM OmniProcess WHERE IsActive=true AND OmniProcessType='OmniScript' LIMIT 50" -o <org>
+
+# Query all elements for a specific OmniScript (ordered by hierarchy)
+sf data query -q "SELECT Id,Name,ElementType,PropertySetConfig,Level,Order FROM OmniProcessElement WHERE OmniProcessId='<id>' ORDER BY Level,Order LIMIT 200" -o <org>
+
+# Retrieve OmniScript metadata from org
+sf project retrieve start -m "OmniScript:<Name>" -o <org>
+
+# Deploy OmniScript metadata to org
+sf project deploy start -m "OmniScript:<Name>" -o <org>
+
+# Check all versions of a specific OmniScript
+sf data query -q "SELECT Id,VersionNumber,IsActive,LastModifiedDate FROM OmniProcess WHERE Type='<Type>' AND SubType='<SubType>' AND OmniProcessType='OmniScript' ORDER BY VersionNumber DESC LIMIT 10" -o <org>
+
+# Verify active version after deployment
+sf data query -q "SELECT Id,Name,Type,SubType,Language,IsActive,VersionNumber FROM OmniProcess WHERE Type='<Type>' AND SubType='<SubType>' AND OmniProcessType='OmniScript' AND IsActive=true LIMIT 5" -o <org>

package/skills/building-omnistudio-omniscript/scripts/deploy-omniscript.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+# Deploy an OmniScript and verify activation.
+# Usage: ./deploy-omniscript.sh <Name> <Type> <SubType> <org>
+# Example: ./deploy-omniscript.sh ServiceRequest_NewCase_English ServiceRequest NewCase myOrg
+# Run AFTER deploying all dependencies (DataRaptors, Integration Procedures).
+
+NAME="${1:?Usage: $0 <Name> <Type> <SubType> <org>}"
+TYPE="${2:?}"
+SUBTYPE="${3:?}"
+ORG="${4:?}"
+
+echo "Step 1: Verify prerequisites — check org auth"
+sf org display -o "${ORG}" || { echo "ERROR: Org '${ORG}' is not authenticated. Run: sf org login web --alias ${ORG}"; exit 1; }
+
+echo "Step 2: Deploy OmniScript metadata"
+sf project deploy start -m "OmniScript:${NAME}" -o "${ORG}"
+if [ $? -ne 0 ]; then
+  echo "ERROR: Deployment failed. To recover:"
+  echo "  1. Check the error message above for the specific cause."
+  echo "  2. If a partial OmniProcess record was created, deactivate and delete it:"
+  echo "     sf data delete record -s OmniProcess -w \"Name='${NAME}'\" -o ${ORG}"
+  echo "  3. Fix the issue and re-run this script."
+  exit 1
+fi
+
+echo "Step 3: Verify activation"
+sf data query \
+  -q "SELECT Id,Name,Type,SubType,Language,IsActive,VersionNumber FROM OmniProcess WHERE Type='${TYPE}' AND SubType='${SUBTYPE}' AND OmniProcessType='OmniScript' AND IsActive=true LIMIT 5" \
+  -o "${ORG}"

package/skills/building-sf-integrations/CREDITS.md

@@ -0,0 +1,5 @@
+# Credits & Acknowledgments
+
+This skill is built on Salesforce integration platform patterns, incorporating security best practices and architectural guidance from the Salesforce platform ecosystem.
+
+---

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

@@ -0,0 +1,95 @@
+# building-sf-integrations
+
+Creates comprehensive Salesforce integrations with 120-point scoring. Build secure Named Credentials, External Services, REST/SOAP callouts, Platform Events, and Change Data Capture patterns.
+
+## Features
+
+- **Named Credentials**: OAuth 2.0, JWT Bearer, Certificate, API Key authentication patterns
+- **External Credentials**: Modern API 61+ credential architecture with Named Principals
+- **External Services**: Auto-generate Apex from OpenAPI/Swagger specs
+- **Callout Patterns**: Synchronous and asynchronous REST/SOAP implementations
+- **Event-Driven**: Platform Events and Change Data Capture subscribers
+- **120-Point Scoring**: Automated validation across 6 categories
+- **Automation Scripts**: Configure credentials without UI (ConnectApi)
+
+
+## Quick Start
+
+### 1. Invoke the skill
+
+```
+Skill: building-sf-integrations
+Request: "Create a Named Credential for Stripe API with OAuth"
+```
+
+### 2. Answer requirements questions
+
+The skill will ask about:
+- Integration type (REST, SOAP, Event-driven)
+- Authentication method (OAuth, JWT, Certificate, API Key)
+- External system details (URL, rate limits)
+- Sync vs Async requirements
+
+### 3. Deploy and configure
+
+```bash
+# Deploy credential metadata
+sf project deploy start --metadata NamedCredential:StripeAPI --target-org MyOrg
+
+# Run automation script to set API key
+./scripts/configure-named-credential.sh MyOrg
+```
+
+## Scoring System (120 Points)
+
+| Category | Points | Focus |
+|----------|--------|-------|
+| Security | 30 | Named Credentials, no hardcoded secrets, OAuth scopes |
+| Error Handling | 25 | Retry logic, timeouts, specific exceptions |
+| Bulkification | 20 | Batch callouts, event batching |
+| Architecture | 20 | Async patterns, service separation |
+| Best Practices | 15 | Governor limits, idempotency |
+| Documentation | 10 | Clear intent, API versioning |
+
+**Thresholds**: ⭐⭐⭐⭐⭐ 90+ | ⭐⭐⭐⭐ 80-89 | ⭐⭐⭐ 70-79 | Block: <45%
+
+## Helper Scripts
+
+Automate credential configuration without manual UI steps:
+
+| Script | Purpose |
+|--------|---------|
+| `configure-named-credential.sh` | Set API keys via ConnectApi (Enhanced NC) |
+| `set-api-credential.sh` | Store keys in Custom Settings (dev/test) |
+
+**Auto-run**: When you create credential files, Claude suggests running these scripts.
+
+```bash
+# After deploying Named Credential metadata
+./scripts/configure-named-credential.sh MyOrg
+# Enter API key when prompted (secure, hidden input)
+```
+
+## Prerequisites
+
+- **Salesforce CLI v2+**: `sf` command
+- **Authenticated org**: `sf org login web -a <alias>`
+- **API Version**: 62.0+ recommended for External Credentials
+
+## Cross-Skill Integration
+
+| Skill | Integration |
+|-------|-------------|
+| configuring-connected-apps | Create OAuth Connected App for Named Credential |
+| generating-apex | Custom callout services beyond templates |
+| generating-flow | HTTP Callout Flow for Agentforce |
+| deploying-metadata | Deploy credentials and callout code |
+| developing-agentforce | Agent actions using External Services |
+
+## Documentation
+
+- [SKILL.md](SKILL.md) - Complete skill reference
+- [references/named-credentials-automation.md](references/named-credentials-automation.md) - Script automation guide
+- [references/named-credentials-guide.md](references/named-credentials-guide.md) - Template reference
+- [references/callout-patterns.md](references/callout-patterns.md) - REST/SOAP patterns
+- [references/event-patterns.md](references/event-patterns.md) - Platform Events & CDC

package/skills/building-sf-integrations/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: building-sf-integrations
+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 configuring-connected-apps), Apex-only logic (use generating-apex), or data import/export (use handling-sf-data)."
+license: MIT
+metadata:
+  version: "1.1"
+---
+
+# building-sf-integrations: 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 `building-sf-integrations` 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 → [configuring-connected-apps](../configuring-connected-apps/SKILL.md)
+- writing Apex-only business logic → [generating-apex](../generating-apex/SKILL.md)
+- deploying metadata → [deploying-metadata](../deploying-metadata/SKILL.md)
+- importing/exporting data → [handling-sf-data](../handling-sf-data/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:
+- [deploying-metadata](../deploying-metadata/SKILL.md) for deployment
+- [generating-apex](../generating-apex/SKILL.md) for deeper service / retry code
+- [generating-flow](../generating-flow/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 | [configuring-connected-apps](../configuring-connected-apps/SKILL.md) | consumer key / cert / app config |
+| advanced callout service code | [generating-apex](../generating-apex/SKILL.md) | Apex implementation |
+| declarative HTTP callout / Flow wrapper | [generating-flow](../generating-flow/SKILL.md) | Flow orchestration |
+| deploy integration metadata | [deploying-metadata](../deploying-metadata/SKILL.md) | validation and rollout |
+| use integration from Agentforce | [developing-agentforce](../developing-agentforce/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/building-sf-integrations/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 {}
+}