@salesforce/afv-skills 1.7.5 → 1.9.0

package/skills/generating-mermaid-diagrams/assets/integration/api-sequence.md

@@ -0,0 +1,387 @@
+# Integration Sequence Diagram Template
+
+Sequence diagram template for visualizing Salesforce integration patterns with external systems.
+
+## When to Use
+- Documenting API integrations
+- Planning data sync flows
+- Designing event-driven architectures
+- Explaining callout patterns
+
+## Mermaid Template - Outbound REST Callout
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': {
+  'actorBkg': '#ddd6fe',
+  'actorTextColor': '#1f2937',
+  'actorBorder': '#6d28d9',
+  'signalColor': '#334155',
+  'signalTextColor': '#1f2937',
+  'noteBkgColor': '#f8fafc',
+  'noteTextColor': '#1f2937',
+  'noteBorderColor': '#334155'
+}}}%%
+sequenceDiagram
+    autonumber
+
+    box rgba(167,243,208,0.3) SALESFORCE
+        participant T as 🔄 Trigger/<br/>Flow
+        participant Q as ⚡ Queueable
+        participant NC as 🔐 Named<br/>Credential
+    end
+
+    box rgba(254,215,170,0.3) EXTERNAL SYSTEM
+        participant API as 🏭 External<br/>API
+    end
+
+    Note over T,API: Outbound REST Integration (Async)
+
+    T->>T: 1. Record Created/Updated
+    Note over T: Account After Insert/Update
+
+    T->>Q: 2. Enqueue Async Job
+    Note over T,Q: System.enqueueJob(<br/>  new AccountSyncQueueable(recordIds)<br/>)
+
+    activate Q
+
+    Q->>Q: 3. Query Records
+    Note over Q: [SELECT Id, Name, ...<br/> FROM Account<br/> WHERE Id IN :recordIds]
+
+    Q->>Q: 4. Build Request Payload
+    Note over Q: JSON.serialize(accounts)
+
+    Q->>NC: 5. Get Auth Token
+    Note over Q,NC: Named Credential handles:<br/>• OAuth token refresh<br/>• Certificate auth<br/>• Basic auth
+
+    NC->>Q: 6. Return Auth Headers
+
+    Q->>API: 7. POST /api/v1/accounts
+    Note over Q,API: Headers:<br/>  Authorization: Bearer ...<br/>  Content-Type: application/json<br/><br/>Body: [{"name": "Acme", ...}]
+
+    alt Success (2xx)
+        API->>Q: 8a. 200 OK
+        Note over API,Q: {"status": "created",<br/> "externalId": "EXT-123"}
+
+        Q->>Q: 9a. Update SF Records
+        Note over Q: Account.External_Id__c = "EXT-123"<br/>Account.Sync_Status__c = "Synced"
+    else Client Error (4xx)
+        API->>Q: 8b. 400 Bad Request
+        Note over API,Q: {"error": "validation_failed",<br/> "details": [...]}
+
+        Q->>Q: 9b. Log Error
+        Note over Q: Create Integration_Log__c<br/>Status = "Failed"
+    else Server Error (5xx)
+        API->>Q: 8c. 500 Internal Error
+
+        Q->>Q: 9c. Retry Logic
+        Note over Q: if (retryCount < 3)<br/>  System.enqueueJob(this)
+    end
+
+    deactivate Q
+```
+
+## Mermaid Template - Inbound REST API
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': {
+  'actorBkg': '#ddd6fe',
+  'actorTextColor': '#1f2937',
+  'actorBorder': '#6d28d9',
+  'signalColor': '#334155',
+  'signalTextColor': '#1f2937',
+  'noteBkgColor': '#f8fafc',
+  'noteTextColor': '#1f2937',
+  'noteBorderColor': '#334155'
+}}}%%
+sequenceDiagram
+    autonumber
+
+    box rgba(254,215,170,0.3) EXTERNAL SYSTEM
+        participant EXT as 🏭 External<br/>System
+    end
+
+    box rgba(167,243,208,0.3) SALESFORCE
+        participant GW as 🌐 API Gateway<br/>(REST Resource)
+        participant SVC as ⚙️ Service<br/>Class
+        participant DB as 💾 Database
+    end
+
+    Note over EXT,DB: Inbound REST Integration
+
+    EXT->>EXT: 1. Prepare Request
+    Note over EXT: Build payload with<br/>account data
+
+    EXT->>GW: 2. POST /services/apexrest/accounts
+    Note over EXT,GW: Headers:<br/>  Authorization: Bearer ACCESS_TOKEN<br/>  Content-Type: application/json
+
+    activate GW
+
+    GW->>GW: 3. Authenticate Request
+    Note over GW: Validate OAuth token<br/>Check user permissions
+
+    GW->>GW: 4. Parse Request Body
+    Note over GW: RestRequest req = RestContext.request<br/>String body = req.requestBody.toString()
+
+    GW->>SVC: 5. Call Service Method
+    Note over GW,SVC: AccountService.upsertAccounts(<br/>  parsedAccounts<br/>)
+
+    activate SVC
+
+    SVC->>SVC: 6. Validate Data
+    Note over SVC: Check required fields<br/>Validate external IDs
+
+    SVC->>DB: 7. Upsert Records
+    Note over SVC,DB: Database.upsert(<br/>  accounts,<br/>  Account.External_Id__c,<br/>  false // allOrNone<br/>)
+
+    DB->>SVC: 8. Return Results
+
+    SVC->>SVC: 9. Process Results
+    Note over SVC: Map success/errors<br/>to response format
+
+    deactivate SVC
+
+    SVC->>GW: 10. Return Response Object
+
+    GW->>GW: 11. Build REST Response
+    Note over GW: RestContext.response.statusCode = 200<br/>RestContext.response.responseBody = JSON
+
+    deactivate GW
+
+    GW->>EXT: 12. 200 OK
+    Note over GW,EXT: {<br/>  "success": true,<br/>  "records": [<br/>    {"id": "001xxx", "status": "created"},<br/>    {"id": "001yyy", "status": "updated"}<br/>  ]<br/>}
+```
+
+## Mermaid Template - Platform Event (Async)
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': {
+  'actorBkg': '#ddd6fe',
+  'actorTextColor': '#1f2937',
+  'actorBorder': '#6d28d9',
+  'signalColor': '#334155',
+  'signalTextColor': '#1f2937',
+  'noteBkgColor': '#f8fafc',
+  'noteTextColor': '#1f2937',
+  'noteBorderColor': '#334155'
+}}}%%
+sequenceDiagram
+    autonumber
+
+    box rgba(167,243,208,0.3) SALESFORCE ORG A
+        participant T as 🔄 Trigger
+        participant PE as 📢 Platform<br/>Event
+    end
+
+    box rgba(165,243,252,0.3) EVENT BUS
+        participant EB as 🚌 Salesforce<br/>Event Bus
+    end
+
+    box rgba(254,215,170,0.3) EXTERNAL SYSTEM
+        participant CL as 🔌 CometD<br/>Client
+        participant API as 🏭 Backend<br/>Service
+    end
+
+    Note over T,API: Event-Driven Integration
+
+    T->>T: 1. Record Change Detected
+    Note over T: Account updated with<br/>Type = 'Customer'
+
+    T->>PE: 2. Publish Platform Event
+    Note over T,PE: EventBus.publish(<br/>  new Account_Change__e(<br/>    Account_Id__c = acc.Id,<br/>    Change_Type__c = 'UPDATE'<br/>  )<br/>)
+
+    PE->>EB: 3. Event Published
+    Note over PE,EB: Event persisted to<br/>event bus (24hr retention)
+
+    EB->>EB: 4. Event Queued
+
+    EB-)CL: 5. Push to Subscribers
+    Note over EB,CL: CometD streaming<br/>/event/Account_Change__e
+
+    activate CL
+
+    CL->>CL: 6. Receive Event
+    Note over CL: {<br/>  "Account_Id__c": "001xxx",<br/>  "Change_Type__c": "UPDATE",<br/>  "ReplayId": 12345<br/>}
+
+    CL->>API: 7. Process Event
+    Note over CL,API: Call internal service<br/>to sync data
+
+    API->>API: 8. Update External DB
+
+    API->>CL: 9. Acknowledge
+    Note over API,CL: Store ReplayId for<br/>resume capability
+
+    deactivate CL
+
+    Note over CL: ⚠️ Store last ReplayId<br/>for reconnection
+```
+
+## ASCII Fallback Template - Outbound Integration
+
+```
+┌───────────────┐  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐
+│    Trigger    │  │   Queueable   │  │     Named     │  │   External    │
+│               │  │               │  │   Credential  │  │     API       │
+└───────┬───────┘  └───────┬───────┘  └───────┬───────┘  └───────┬───────┘
+        │                  │                  │                  │
+        │  1. Record       │                  │                  │
+        │     Changed      │                  │                  │
+        │                  │                  │                  │
+        │  2. Enqueue Job  │                  │                  │
+        │─────────────────>│                  │                  │
+        │                  │                  │                  │
+        │                  │  3. Query        │                  │
+        │                  │     Records      │                  │
+        │                  │                  │                  │
+        │                  │  4. Get Auth     │                  │
+        │                  │─────────────────>│                  │
+        │                  │                  │                  │
+        │                  │  5. Auth Token   │                  │
+        │                  │<─────────────────│                  │
+        │                  │                  │                  │
+        │                  │  6. POST /api/accounts              │
+        │                  │─────────────────────────────────────>│
+        │                  │                  │                  │
+        │                  │  7. Response (200/4xx/5xx)          │
+        │                  │<─────────────────────────────────────│
+        │                  │                  │                  │
+        │                  │  8. Update       │                  │
+        │                  │     Records      │                  │
+        │                  │     (or retry)   │                  │
+```
+
+## Common Integration Patterns
+
+### 1. Request-Response (Sync)
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': {
+  'actorBkg': '#ddd6fe',
+  'actorTextColor': '#1f2937',
+  'actorBorder': '#6d28d9',
+  'signalColor': '#334155'
+}}}%%
+sequenceDiagram
+    participant SF as Salesforce
+    participant EXT as External API
+    SF->>EXT: Request
+    EXT->>SF: Response
+```
+
+### 2. Fire-and-Forget (Async)
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': {
+  'actorBkg': '#ddd6fe',
+  'actorTextColor': '#1f2937',
+  'actorBorder': '#6d28d9',
+  'signalColor': '#334155'
+}}}%%
+sequenceDiagram
+    participant SF as Salesforce
+    participant Q as Queue
+    participant EXT as External API
+    SF-)Q: Enqueue
+    Q-)EXT: Process (later)
+```
+
+### 3. Pub/Sub (Event-Driven)
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': {
+  'actorBkg': '#ddd6fe',
+  'actorTextColor': '#1f2937',
+  'actorBorder': '#6d28d9',
+  'signalColor': '#334155'
+}}}%%
+sequenceDiagram
+    participant PUB as Publisher
+    participant BUS as Event Bus
+    participant SUB as Subscriber
+    PUB-)BUS: Publish Event
+    BUS-)SUB: Deliver Event
+```
+
+### 4. Batch Sync
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': {
+  'actorBkg': '#ddd6fe',
+  'actorTextColor': '#1f2937',
+  'actorBorder': '#6d28d9',
+  'signalColor': '#334155'
+}}}%%
+sequenceDiagram
+    participant SCH as Scheduler
+    participant BAT as Batch Job
+    participant EXT as External API
+    SCH->>BAT: Start (daily)
+    loop Each Batch
+        BAT->>EXT: Sync Records
+    end
+```
+
+## HTTP Method Reference
+
+| Method | Purpose | Salesforce Use |
+|--------|---------|----------------|
+| GET | Retrieve data | Query external API |
+| POST | Create resource | Send new records |
+| PUT | Replace resource | Full record update |
+| PATCH | Partial update | Update specific fields |
+| DELETE | Remove resource | Delete external record |
+
+## Error Handling Patterns
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': {
+  'actorBkg': '#ddd6fe',
+  'actorTextColor': '#1f2937',
+  'actorBorder': '#6d28d9',
+  'signalColor': '#334155',
+  'signalTextColor': '#1f2937',
+  'noteBkgColor': '#f8fafc',
+  'noteTextColor': '#1f2937'
+}}}%%
+sequenceDiagram
+    participant SF as Salesforce
+    participant API as External API
+
+    SF->>API: Request
+
+    alt Success
+        API->>SF: 200 OK
+        SF->>SF: Process Response
+    else Retry-able Error
+        API->>SF: 503 Service Unavailable
+        SF->>SF: Wait (exponential backoff)
+        SF->>API: Retry Request
+    else Fatal Error
+        API->>SF: 400 Bad Request
+        SF->>SF: Log Error
+        SF->>SF: Create Case/Task
+    end
+```
+
+## Salesforce Integration Components
+
+| Component | Purpose | When to Use |
+|-----------|---------|-------------|
+| Named Credential | Auth management | OAuth, Certificate, Basic Auth |
+| External Service | Auto-generate Apex | OpenAPI/Swagger specs |
+| Platform Event | Async messaging | Event-driven integration |
+| Change Data Capture | Track changes | Real-time replication |
+| Outbound Message | Declarative callout | Simple workflow integrations |
+| Apex REST | Inbound API | Custom REST endpoints |
+| SOAP API | Inbound SOAP | Legacy systems |
+
+## Best Practices
+
+1. **Always use async** for callouts in triggers
+2. **Use Named Credentials** for auth management
+3. **Implement retry logic** with exponential backoff
+4. **Log all integrations** for troubleshooting
+5. **Handle partial success** in bulk operations
+6. **Set appropriate timeouts** (max 120s for callouts)
+
+## Customization Points
+
+- Replace system names with actual integration partners
+- Add specific endpoints and payload structures
+- Include actual field mappings
+- Show specific error codes and handling

package/skills/generating-mermaid-diagrams/assets/oauth/authorization-code-pkce.md

@@ -0,0 +1,197 @@
+# Authorization Code + PKCE Flow Template
+
+OAuth 2.0 Authorization Code flow with Proof Key for Code Exchange (PKCE) for public clients.
+
+## When to Use
+- Single Page Applications (SPAs)
+- Mobile native applications
+- Desktop applications
+- Any client that cannot securely store a client_secret
+
+## Mermaid Template
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': {
+  'actorBkg': '#ddd6fe',
+  'actorTextColor': '#1f2937',
+  'actorBorder': '#6d28d9',
+  'signalColor': '#334155',
+  'signalTextColor': '#1f2937',
+  'noteBkgColor': '#f8fafc',
+  'noteTextColor': '#1f2937',
+  'noteBorderColor': '#334155'
+}}}%%
+sequenceDiagram
+    autonumber
+
+    box rgba(165,243,252,0.3) USER DEVICE
+        participant U as 👤 User
+        participant App as 📱 Mobile App<br/>or SPA
+    end
+
+    box rgba(167,243,208,0.3) SALESFORCE
+        participant SF as ☁️ Salesforce<br/>Authorization Server
+    end
+
+    Note over U,SF: Authorization Code + PKCE Flow (RFC 7636)
+
+    U->>App: 1. Tap "Login with Salesforce"
+
+    App->>App: 2. Generate PKCE Parameters
+    Note over App: code_verifier = random(128 bytes)<br/>code_challenge = BASE64URL(SHA256(code_verifier))
+
+    App->>App: 3. Generate state (CSRF protection)
+
+    App->>SF: 4. Open browser/webview to /authorize
+    Note over App,SF: response_type=code<br/>client_id=CONSUMER_KEY<br/>redirect_uri=CALLBACK_URL<br/>scope=api refresh_token<br/>state=RANDOM_STATE<br/>code_challenge=CODE_CHALLENGE<br/>code_challenge_method=S256
+
+    SF->>U: 5. Display Login Page
+    U->>SF: 6. Enter Username & Password
+
+    SF->>SF: 7. Authenticate User
+
+    SF->>U: 8. Display Consent Screen
+    Note over SF,U: "App requests access to:<br/>• API Access<br/>• Refresh Token"
+
+    U->>SF: 9. Grant Consent (Allow)
+
+    SF->>SF: 10. Generate Authorization Code
+    Note over SF: Store code_challenge with code
+
+    SF->>App: 11. Redirect to callback with code
+    Note over SF,App: scheme://callback?code=AUTH_CODE<br/>&state=RANDOM_STATE
+
+    App->>App: 12. Verify state matches
+
+    App->>SF: 13. POST /services/oauth2/token
+    Note over App,SF: grant_type=authorization_code<br/>code=AUTH_CODE<br/>client_id=CONSUMER_KEY<br/>redirect_uri=CALLBACK_URL<br/>code_verifier=CODE_VERIFIER
+
+    SF->>SF: 14. Validate Code & PKCE
+    Note over SF: Verify: BASE64URL(SHA256(code_verifier))<br/>== stored code_challenge
+
+    SF->>App: 15. Return Tokens
+    Note over SF,App: {<br/>  access_token: "...",<br/>  refresh_token: "...",<br/>  instance_url: "https://...",<br/>  token_type: "Bearer"<br/>}
+
+    App->>App: 16. Store tokens securely
+    Note over App: Use Keychain (iOS)<br/>or Keystore (Android)
+
+    App->>U: 17. ✅ Successfully Logged In
+```
+
+## ASCII Fallback Template
+
+```
+┌──────────┐     ┌───────────────┐     ┌────────────────────┐
+│  User    │     │  Mobile App   │     │     Salesforce     │
+│          │     │   or SPA      │     │   (Auth Server)    │
+└────┬─────┘     └───────┬───────┘     └─────────┬──────────┘
+     │                   │                       │
+     │  1. Tap Login     │                       │
+     │──────────────────>│                       │
+     │                   │                       │
+     │                   │  2. Generate PKCE:    │
+     │                   │     code_verifier     │
+     │                   │     code_challenge    │
+     │                   │                       │
+     │  3. Open Browser/WebView to /authorize    │
+     │<──────────────────│                       │
+     │                   │                       │
+     │  4. GET /authorize                        │
+     │      (client_id, code_challenge, state)   │
+     │───────────────────────────────────────────────────────>│
+     │                   │                       │
+     │           5. Login Page                   │
+     │<───────────────────────────────────────────────────────│
+     │                   │                       │
+     │  6. Enter Credentials                     │
+     │───────────────────────────────────────────────────────>│
+     │                   │                       │
+     │           7. Consent Screen               │
+     │<───────────────────────────────────────────────────────│
+     │                   │                       │
+     │  8. Grant Consent                         │
+     │───────────────────────────────────────────────────────>│
+     │                   │                       │
+     │  9. Redirect with ?code=ABC123            │
+     │<───────────────────────────────────────────────────────│
+     │                   │                       │
+     │ 10. Deliver Code  │                       │
+     │──────────────────>│                       │
+     │                   │                       │
+     │                   │ 11. POST /token       │
+     │                   │     (code_verifier)   │
+     │                   │──────────────────────>│
+     │                   │                       │
+     │                   │ 12. Verify PKCE:      │
+     │                   │     SHA256(verifier)  │
+     │                   │     == challenge      │
+     │                   │                       │
+     │                   │ 13. Access Token +    │
+     │                   │     Refresh Token     │
+     │                   │<──────────────────────│
+     │                   │                       │
+     │ 14. Logged In ✅  │                       │
+     │<──────────────────│                       │
+```
+
+## PKCE Parameter Generation
+
+### JavaScript/TypeScript
+```javascript
+// Generate code_verifier (43-128 characters)
+const codeVerifier = base64URLEncode(crypto.getRandomValues(new Uint8Array(32)));
+
+// Generate code_challenge
+const encoder = new TextEncoder();
+const data = encoder.encode(codeVerifier);
+const digest = await crypto.subtle.digest('SHA-256', data);
+const codeChallenge = base64URLEncode(new Uint8Array(digest));
+
+function base64URLEncode(buffer) {
+  return btoa(String.fromCharCode(...buffer))
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+}
+```
+
+### Python
+```python
+import hashlib
+import base64
+import secrets
+
+# Generate code_verifier
+code_verifier = base64.urlsafe_b64encode(secrets.token_bytes(32)).rstrip(b'=').decode()
+
+# Generate code_challenge
+code_challenge = base64.urlsafe_b64encode(
+    hashlib.sha256(code_verifier.encode()).digest()
+).rstrip(b'=').decode()
+```
+
+## Key Differences from Standard Auth Code
+
+| Aspect | Standard | PKCE |
+|--------|----------|------|
+| Client Secret | Required | Not required |
+| code_challenge | Not used | Required in /authorize |
+| code_verifier | Not used | Required in /token |
+| Security | Secret-based | Cryptographic proof |
+| Client Type | Confidential | Public |
+
+## Security Considerations
+
+1. **Generate new PKCE values** for each authorization request
+2. **Use S256 method** (SHA-256), never "plain"
+3. **Store code_verifier securely** until token exchange
+4. **Use secure storage** for tokens (Keychain/Keystore)
+5. **Implement refresh token rotation** for additional security
+
+## Customization Points
+
+Replace these placeholders:
+- `CONSUMER_KEY` → Your Connected App's Consumer Key
+- `CALLBACK_URL` → Your registered callback URL (custom scheme for mobile)
+- `CODE_VERIFIER` → Generated 43-128 character random string
+- `CODE_CHALLENGE` → BASE64URL(SHA256(CODE_VERIFIER))