npm - @salesforce/afv-skills - Versions diffs - 1.22.0 → 1.24.0 - Mend

@salesforce/afv-skills 1.22.0 → 1.24.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1675) hide show

package/skills/building-sf-integrations/references/cdc-guide.md DELETED Viewed

@@ -1,288 +0,0 @@
-<!-- Parent: building-sf-integrations/SKILL.md -->
-# Change Data Capture (CDC) Guide
-## Overview
-Change Data Capture publishes change events for Salesforce records, enabling near real-time data synchronization with external systems.
-## How CDC Works
-```
-┌─────────────────────────────────────────────────────────────────┐
-│  CHANGE DATA CAPTURE FLOW                                       │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                 │
-│  1. Record Created/Updated/Deleted in Salesforce                │
-│     ↓                                                           │
-│  2. Salesforce generates Change Event                           │
-│     ↓                                                           │
-│  3. Event published to {{Object}}ChangeEvent channel            │
-│     ↓                                                           │
-│  4. Apex Trigger or External Subscriber receives event          │
-│     ↓                                                           │
-│  5. Process event (sync, audit, notify)                         │
-│                                                                 │
-└─────────────────────────────────────────────────────────────────┘
-```
-## CDC vs Platform Events
-| Feature | CDC | Platform Events |
-|---------|-----|-----------------|
-| Trigger | Automatic on DML | Manual publish |
-| Schema | Predefined (object fields) | Custom defined |
-| Use Case | Data sync/replication | Custom messaging |
-| Control | Limited | Full control |
-## Enabling CDC
-### Via Setup
-1. Go to **Setup → Integrations → Change Data Capture**
-2. Select objects to enable
-3. Save
-### Supported Objects
-- Most Standard objects (Account, Contact, Opportunity, etc.)
-- Custom objects
-- Some system objects (User, Group, etc.)
-## Event Channel Names
-| Object Type | Channel Name |
-|-------------|--------------|
-| Standard | `AccountChangeEvent`, `ContactChangeEvent` |
-| Custom | `My_Object__ChangeEvent` (append ChangeEvent) |
-## Change Event Structure
-### ChangeEventHeader
-```apex
-EventBus.ChangeEventHeader header = event.ChangeEventHeader;
-// Available methods
-header.getChangeType();       // CREATE, UPDATE, DELETE, UNDELETE
-header.getChangedFields();    // List of changed field API names
-header.getRecordIds();        // Affected record IDs
-header.getEntityName();       // Object API name
-header.getCommitNumber();     // Transaction sequence
-header.getCommitTimestamp();  // When change occurred
-header.getTransactionKey();   // Unique transaction ID
-```
-### Change Types
-| Type | Description | Event Contains |
-|------|-------------|----------------|
-| CREATE | New record | All field values |
-| UPDATE | Record modified | Changed field values only |
-| DELETE | Record deleted | Record IDs only |
-| UNDELETE | Restored from bin | All field values |
-| GAP_* | Events missed | Affected record IDs |
-| GAP_OVERFLOW | Too many changes | Entity name |
-### Field Values
-- **Changed fields**: Contain new values
-- **Unchanged fields**: Null
-- Use `getChangedFields()` to know what changed
-## Subscribing to CDC
-### Apex Trigger
-```apex
-trigger AccountCDC on AccountChangeEvent (after insert) {
-    for (AccountChangeEvent event : Trigger.new) {
-        EventBus.ChangeEventHeader header = event.ChangeEventHeader;
-        String changeType = header.getChangeType();
-        List<String> changedFields = header.getChangedFields();
-        List<String> recordIds = header.getRecordIds();
-        switch on changeType {
-            when 'CREATE' {
-                // Handle new records
-            }
-            when 'UPDATE' {
-                // Handle updates
-            }
-            when 'DELETE' {
-                // Handle deletions
-            }
-        }
-    }
-    // Set checkpoint
-    EventBus.TriggerContext.currentContext().setResumeCheckpoint(
-        Trigger.new[Trigger.new.size()-1].ReplayId
-    );
-}
-```
-### External (CometD)
-```
-Channel: /data/AccountChangeEvent
-```
-## Handling Specific Changes
-### Filter by Changed Fields
-```apex
-// Only process if important fields changed
-Set<String> importantFields = new Set<String>{'Status__c', 'Amount__c'};
-List<String> changedFields = header.getChangedFields();
-Boolean relevant = false;
-for (String field : changedFields) {
-    if (importantFields.contains(field)) {
-        relevant = true;
-        break;
-    }
-}
-if (!relevant) return;
-```
-### Get New Values
-```apex
-// Access field values from event (UPDATE: only changed fields have values)
-if (changedFields.contains('Status__c')) {
-    String newStatus = event.Status__c;
-    // Process status change
-}
-```
-## Gap Events
-Gap events indicate missed events:
-### Types
-| Event | Meaning | Action |
-|-------|---------|--------|
-| GAP_CREATE | Missed creates | Query and sync records |
-| GAP_UPDATE | Missed updates | Query current state |
-| GAP_DELETE | Missed deletes | Reconcile with source |
-| GAP_UNDELETE | Missed restores | Query and sync |
-| GAP_OVERFLOW | Too many changes | Full sync required |
-### Handling Gaps
-```apex
-when 'GAP_CREATE', 'GAP_UPDATE', 'GAP_DELETE', 'GAP_UNDELETE' {
-    // Query current state and sync
-    List<Account> records = [
-        SELECT Id, Name, Status__c
-        FROM Account
-        WHERE Id IN :header.getRecordIds()
-    ];
-    syncToExternalSystem(records);
-}
-when 'GAP_OVERFLOW' {
-    // Trigger full sync batch job
-    Database.executeBatch(new FullSyncBatch());
-}
-```
-## Replay and Durability
-### Retention
-CDC events retained for **3 days** (72 hours).
-### Replay ID
-Each event has unique ReplayId for tracking:
-```apex
-String replayId = event.ReplayId;
-```
-### Resume Checkpoint
-Critical for durability:
-```apex
-// Always set checkpoint at end of trigger
-EventBus.TriggerContext.currentContext().setResumeCheckpoint(lastReplayId);
-```
-If trigger fails after checkpoint, processing resumes from that point.
-## External Sync Pattern
-```apex
-public class AccountCDCHandler {
-    public static void syncToExternal(AccountChangeEvent event) {
-        EventBus.ChangeEventHeader header = event.ChangeEventHeader;
-        Map<String, Object> payload = new Map<String, Object>{
-            'recordIds' => header.getRecordIds(),
-            'operation' => header.getChangeType(),
-            'timestamp' => header.getCommitTimestamp(),
-            'changedFields' => header.getChangedFields()
-        };
-        // Add field values for CREATE/UPDATE
-        if (header.getChangeType() != 'DELETE') {
-            payload.put('name', event.Name);
-            payload.put('accountNumber', event.AccountNumber);
-            // Add relevant fields
-        }
-        // Queue async callout
-        System.enqueueJob(new ExternalSyncJob(payload));
-    }
-}
-```
-## Best Practices
-### DO
-1. **Set resume checkpoint** in every trigger
-2. **Filter by relevant fields** to reduce noise
-3. **Handle all change types** including GAPs
-4. **Process idempotently** (events may replay)
-5. **Use async** for external callouts
-6. **Log changes** for debugging
-### DON'T
-1. **Don't throw exceptions** - catch and log
-2. **Don't ignore GAP events** - they indicate data loss
-3. **Don't assume single record** - batch DML creates multi-record events
-4. **Don't block on external calls** - use Queueable
-## Monitoring
-### Event Delivery
-Check for failures in:
-- Setup → Platform Events → Monitor
-- Debug logs for triggers
-### Common Issues
-| Issue | Cause | Solution |
-|-------|-------|----------|
-| Missing events | No CDC enabled | Enable in Setup |
-| Duplicate processing | No idempotency | Check transactionKey |
-| GAP events | Processing too slow | Optimize trigger, scale out |
-| Timeout | Heavy processing | Move to async |
-## Limits
-| Limit | Value |
-|-------|-------|
-| Objects per org | 100 |
-| Events per 15 minutes | Varies by edition |
-| Event retention | 3 days (72 hours) |
-| Replay window | 3 days |

package/skills/building-sf-integrations/references/cli-reference.md DELETED Viewed

@@ -1,94 +0,0 @@
-<!-- Parent: building-sf-integrations/SKILL.md -->
-# CLI Commands & Helper Scripts
-## Named Credentials
-```bash
-# List Named Credentials
-sf org list metadata --metadata-type NamedCredential --target-org {{alias}}
-# Deploy Named Credential
-sf project deploy start --metadata NamedCredential:{{Name}} --target-org {{alias}}
-# Retrieve Named Credential
-sf project retrieve start --metadata NamedCredential:{{Name}} --target-org {{alias}}
-```
-## External Services
-```bash
-# List External Service Registrations
-sf org list metadata --metadata-type ExternalServiceRegistration --target-org {{alias}}
-# Deploy External Service
-sf project deploy start --metadata ExternalServiceRegistration:{{Name}} --target-org {{alias}}
-```
-## Platform Events
-```bash
-# List Platform Events
-sf org list metadata --metadata-type CustomObject --target-org {{alias}} | grep "__e"
-# Deploy Platform Event
-sf project deploy start --metadata CustomObject:{{EventName}}__e --target-org {{alias}}
-```
-## API Requests (Beta)
-```bash
-# REST API request
-sf api request rest /services/data/v66.0/sobjects/Account/describe --target-org {{alias}}
-# REST with POST body
-sf api request rest /services/data/v66.0/sobjects/Account --method POST \
-  --body '{"Name":"Test Account"}' --target-org {{alias}}
-# GraphQL query
-sf api request graphql --body '{"query":"{ uiapi { query { Account { edges { node { Name { value } } } } } } }"}' --target-org {{alias}}
-```
-> **[Beta]** These commands simplify API exploration. For production, use Named Credentials and Apex callouts.
----
-## Helper Scripts
-building-sf-integrations includes automation scripts to configure credentials without manual UI steps.
-### Available Scripts
-| Script | Purpose | Usage |
-|--------|---------|-------|
-| `configure-named-credential.sh` | Set API keys via ConnectApi (Enhanced NC) | `./scripts/configure-named-credential.sh <org-alias>` |
-| `set-api-credential.sh` | Store keys in Custom Settings (legacy) | `./scripts/set-api-credential.sh <name> - <org-alias>` |
-### Auto-Run Behavior
-| File Pattern | Suggested Action |
-|--------------|------------------|
-| `*.namedCredential-meta.xml` | Run `configure-named-credential.sh` |
-| `*.externalCredential-meta.xml` | Run `configure-named-credential.sh` |
-| `*.cspTrustedSite-meta.xml` | Deploy endpoint security |
-### Example Workflow
-```bash
-# 1. Deploy metadata first
-sf project deploy start --metadata ExternalCredential:WeatherAPI \
-  --metadata NamedCredential:WeatherAPI \
-  --target-org MyOrg
-# 2. Run automation script
-./scripts/configure-named-credential.sh MyOrg
-# Enter API key when prompted (secure, hidden input)
-```
-### Prerequisites
-- **Salesforce CLI v2+**: `sf` command available
-- **Authenticated org**: `sf org login web -a <alias>`
-- **Deployed metadata**: External Credential and Named Credential deployed
-See [references/named-credentials-automation.md](../references/named-credentials-automation.md) for complete guide.

package/skills/building-sf-integrations/references/event-driven-architecture-guide.md DELETED Viewed

@@ -1,266 +0,0 @@
-<!-- Parent: building-sf-integrations/SKILL.md -->
-# Event-Driven Architecture Guide
-> **Source**: Salesforce Architect Decision Guides — Event-Driven Architecture, Async Processing
-> **Related**: [event-patterns.md](./event-patterns.md) | [callout-patterns.md](./callout-patterns.md)
----
-## Overview
-Event-Driven Architecture (EDA) decouples producers from consumers, enabling scalable, resilient integrations. Salesforce supports multiple event mechanisms — choosing the right one depends on volume, latency, and consumer location.
----
-## 5 Core EDA Patterns
-### Pattern Comparison Matrix
-| Pattern | Description | Salesforce Implementation | Best For |
-|---------|-------------|--------------------------|----------|
-| **Pub/Sub** | Publisher emits, multiple subscribers consume | Platform Events + Pub/Sub API | Multi-consumer notifications, cross-system sync |
-| **Fanout** | One event → multiple independent consumers | Platform Events + multiple subscribers | Parallel processing, diverse downstream systems |
-| **Passed Messages** | Event carries data payload for consumer processing | Platform Events with rich fields | External systems needing full context in message |
-| **Streaming** | Continuous data feed for real-time consumers | CDC + Pub/Sub API | Data replication, real-time dashboards |
-| **Queueing** | Ordered, guaranteed-delivery message processing | Platform Events (High-Volume) with checkpoints | Sequential processing, backpressure handling |
-### When to Use Each
-**Pub/Sub**: Default choice for most event-driven integrations. Works for both internal (Apex triggers) and external (Pub/Sub API) consumers.
-**Fanout**: When a single business event (e.g., "Order Placed") needs to notify billing, shipping, analytics, and notifications simultaneously.
-**Passed Messages**: When the consumer needs all context in the event itself (no callback to Salesforce). Keep payloads lean — 1 MB limit.
-**Streaming**: For data replication to warehouses or lakes. CDC + Pub/Sub API replaces legacy Streaming API.
-**Queueing**: When processing order matters and you need backpressure handling. Use High-Volume Platform Events with resume checkpoints.
----
-## Pub/Sub API (Recommended External Subscription)
-The Pub/Sub API is the **recommended mechanism for external consumers** subscribing to Platform Events and CDC events. It replaces the legacy Streaming API (CometD).
-### Key Characteristics
-| Feature | Pub/Sub API | Legacy Streaming API (Deprecated) |
-|---------|-------------|----------------------------------|
-| **Protocol** | gRPC | CometD (long-polling) |
-| **Authentication** | OAuth 2.0 | Session-based |
-| **Event Types** | Platform Events, CDC, Custom Channels | PushTopic, Generic Events, Platform Events |
-| **Performance** | High throughput, binary protocol | Limited by long-polling overhead |
-| **Status** | **Current — use for all new development** | Deprecated — no new investments |
-### Subscription Modes
-- **Subscribe**: Stream events from a given replay ID forward
-- **PublishStream**: Bi-directional — publish events via gRPC (no Apex needed)
-- **ManagedSubscribe**: Salesforce manages replay state (simplest for external consumers)
-### External Consumer Architecture
-```
-Salesforce Org
-  └── Platform Event / CDC Event
-        └── Pub/Sub API (gRPC endpoint)
-              └── External Consumer (Java, Python, Node.js, Go)
-                    ├── Process event
-                    ├── Commit replay ID
-                    └── Handle failures with retry
-```
-### LWC Subscription (Internal)
-For Lightning Web Components subscribing to Platform Events, use **empApi**:
-```javascript
-import { subscribe, unsubscribe, onError } from 'lightning/empApi';
-const channelName = '/event/Order_Status__e';
-let subscription = {};
-connectedCallback() {
-    subscribe(channelName, -1, (response) => {
-        console.log('Event received:', JSON.stringify(response));
-        this.handleEvent(response.data.payload);
-    }).then((sub) => {
-        subscription = sub;
-    });
-    onError((error) => {
-        console.error('empApi error:', JSON.stringify(error));
-    });
-}
-disconnectedCallback() {
-    unsubscribe(subscription);
-}
-```
----
-## Event Relays to AWS EventBridge
-Salesforce Event Relays forward Platform Events to AWS EventBridge, enabling cloud-native event processing.
-### Architecture
-```
-Salesforce Platform Event
-  └── Event Relay Definition (Metadata)
-        └── AWS EventBridge Partner Event Source
-              ├── AWS Lambda
-              ├── AWS SQS
-              ├── AWS Step Functions
-              └── Any EventBridge target
-```
-### When to Use
-- AWS-native architecture needing Salesforce events
-- Complex event processing requiring AWS services (Step Functions, SQS, SNS)
-- Fan-out to multiple AWS consumers from a single Salesforce event
-- Event archival in AWS S3 or data lakes
-### Limitations
-- One-way only (Salesforce → AWS)
-- Adds latency (~seconds) compared to direct Pub/Sub API
-- Requires AWS account configuration and IAM setup
-- Platform Event limits still apply on the Salesforce side
----
-## Apache Kafka on Heroku
-For organizations needing long-retention, high-throughput event streaming beyond Platform Event limits.
-### Comparison with Platform Events
-| Feature | Platform Events | Kafka on Heroku |
-|---------|----------------|-----------------|
-| **Retention** | 24h (HV) / 72h (SV) | 1-6 weeks (configurable) |
-| **Throughput** | Millions/day (HV) | Millions/second |
-| **Consumer groups** | Limited | Unlimited |
-| **Replay** | ReplayId-based | Offset-based, topic-level |
-| **Cost** | Included / Platform Event add-on | Heroku Kafka add-on |
-### When to Choose Kafka
-- Retention > 72 hours required
-- Need multiple independent consumer groups
-- Event throughput exceeds Platform Event limits
-- Existing Kafka ecosystem in organization
-- Need topic partitioning for ordered processing
-### Integration Pattern
-```
-Salesforce → Platform Event → Apex/Flow subscriber → Heroku Kafka producer
-                                                        └── Consumer Group A (analytics)
-                                                        └── Consumer Group B (data lake)
-                                                        └── Consumer Group C (external CRM)
-```
----
-## When NOT to Use Events
-Events are not always the right choice. Prefer synchronous patterns when:
-| Scenario | Why Not Events | Better Alternative |
-|----------|---------------|-------------------|
-| **Need synchronous response** | Events are async — no return value | REST callout with Named Credential |
-| **Infrequent data changes** | Event infrastructure overhead not justified | Scheduled batch sync |
-| **Target system lacks event support** | Consumer can't subscribe to events | Outbound Messages or REST callout |
-| **Simple record sync** | Over-engineering for basic needs | Salesforce Connect / External Objects |
-| **Data volume < 100 records/day** | Platform Event overhead unnecessary | Scheduled Flow with REST callout |
----
-## High-Volume Outbound Pattern
-For scenarios requiring high-volume data push to external systems:
-> **Do NOT use async Apex directly for high-volume outbound.** Apex async limits (250K daily Queueable, 250K daily @future) are shared across all org operations. Consuming them for outbound sync starves other automation.
-### Recommended Pattern: Middleware + Platform Events
-```
-Salesforce Record Change
-  └── After-Save Flow / Trigger
-        └── Publish Platform Event (lightweight payload)
-              └── External Middleware (MuleSoft, Pub/Sub API consumer)
-                    ├── Enrich data (callback to Salesforce REST API if needed)
-                    ├── Transform to target format
-                    ├── Deliver to target system with retry logic
-                    └── Report status back via Platform Event or REST callback
-```
-### Benefits
-- **No Apex async limit consumption** — events don't count against daily limits
-- **Middleware handles retries** — exponential backoff, dead letter queues
-- **Scalable** — middleware scales independently of Salesforce
-- **Observable** — middleware provides logging, monitoring, alerting
----
-## Monitoring Event-Driven Systems
-### AsyncApexJob Monitoring
-Query job status for async Apex that processes events:
-```apex
-List<AsyncApexJob> jobs = [
-    SELECT Id, JobType, Status, NumberOfErrors, MethodName, CreatedDate
-    FROM AsyncApexJob
-    WHERE CreatedDate = TODAY
-    AND Status IN ('Failed', 'Aborted')
-    ORDER BY CreatedDate DESC
-    LIMIT 50
-];
-```
-> **Polling limit**: AsyncApexJob queries are subject to SOQL limits. Max polling frequency: every 5 minutes.
-### Platform Event Metrics
-- **Setup → Platform Events → Usage**: View publish/subscribe counts
-- **EventBusSubscriber**: Query for subscriber status and position
-- **Proactive Monitoring**: Set up Flow or Apex to alert on failed event processing
-```apex
-// Check subscriber lag
-List<EventBusSubscriber> subs = [
-    SELECT Name, Position, Retries, LastError, Status
-    FROM EventBusSubscriber
-    WHERE Topic = 'Order_Status__e'
-];
-```
-### Key Metrics to Monitor
-| Metric | Source | Alert Threshold |
-|--------|--------|-----------------|
-| Failed events | `EventBusSubscriber.Retries` | > 3 consecutive retries |
-| Subscriber lag | `EventBusSubscriber.Position` vs latest ReplayId | Lag > 1000 events |
-| Async job failures | `AsyncApexJob.NumberOfErrors` | Any failure |
-| Event publish errors | `Database.SaveResult` in publisher | Any failure |
-| Daily event usage | Setup → Company Information → Platform Event Usage | > 80% of allocation |
----
-## Summary: EDA Decision Tree
-```
-Need real-time data sync?
-  ├── YES → Is consumer external?
-  │    ├── YES → Pub/Sub API + Platform Events (or CDC for record changes)
-  │    └── NO → Platform Event trigger subscriber (or empApi for LWC)
-  └── NO → Is volume high (>10K records/day)?
-       ├── YES → Middleware + Platform Events (high-volume outbound pattern)
-       └── NO → Scheduled batch sync (simplest, most maintainable)
-```