@salesforce/afv-skills 1.1.0 → 1.3.0

package/skills/managing-webapp-agentforce-conversation-client/references/style-tokens.md

@@ -0,0 +1,101 @@
+# Style Tokens Reference
+
+This document explains how to use `styleTokens` for theming and styling the AgentforceConversationClient.
+
+## Overview
+
+The `styleTokens` prop is the **ONLY** way to customize the appearance of the Agentforce conversation client. It accepts an object with style token keys and CSS values.
+
+## Source of Truth
+
+For the complete and always up-to-date list of all 60+ style tokens, see:
+
+**[@salesforce/agentforce-conversation-client on npm](https://www.npmjs.com/package/@salesforce/agentforce-conversation-client)**
+
+The npm package README contains the definitive documentation with all available style tokens.
+
+## Token Categories
+
+Style tokens are organized by UI area:
+
+- **Header** (7 tokens): background, text color, hover, active, focus, border, font family
+- **Messages** (10 tokens): colors, padding, margins, border radius, fonts, body width
+- **Inbound messages** (5 tokens): background, text color, width, alignment, hover
+- **Outbound messages** (5 tokens): background, text color, width, alignment, margin
+- **Input** (33 tokens): colors, borders, fonts, padding, buttons, scrollbar, textarea, actions
+
+## Common Use Cases
+
+### Change header color
+
+```tsx
+<AgentforceConversationClient
+  agentId="0Xx..."
+  styleTokens={{
+    headerBlockBackground: "#0176d3",
+    headerBlockTextColor: "#ffffff",
+  }}
+/>
+```
+
+### Change message colors
+
+```tsx
+<AgentforceConversationClient
+  agentId="0Xx..."
+  styleTokens={{
+    messageBlockInboundBackgroundColor: "#4CAF50",
+    messageBlockInboundTextColor: "#ffffff",
+    messageBlockOutboundBackgroundColor: "#f5f5f5",
+    messageBlockOutboundTextColor: "#333333",
+  }}
+/>
+```
+
+### Apply brand colors
+
+```tsx
+<AgentforceConversationClient
+  agentId="0Xx..."
+  styleTokens={{
+    headerBlockBackground: "#1a73e8",
+    headerBlockTextColor: "#ffffff",
+    messageBlockInboundBackgroundColor: "#1a73e8",
+    messageBlockInboundTextColor: "#ffffff",
+    messageInputFooterSendButton: "#1a73e8",
+    messageInputFooterSendButtonHoverColor: "#1557b0",
+  }}
+/>
+```
+
+### Adjust spacing and fonts
+
+```tsx
+<AgentforceConversationClient
+  agentId="0Xx..."
+  styleTokens={{
+    messageInputFontSize: "16px",
+    messageBlockBorderRadius: "12px",
+    messageBlockPadding: "16px",
+    messageInputPadding: "12px",
+  }}
+/>
+```
+
+## How to Find Token Names
+
+1. Check the [@salesforce/agentforce-conversation-client npm package](https://www.npmjs.com/package/@salesforce/agentforce-conversation-client) for the complete list of all tokens
+
+2. Token names follow a pattern:
+   - `headerBlock*` - Header area
+   - `messageBlock*` - Message bubbles
+   - `messageBlockInbound*` - Messages from customer to agent
+   - `messageBlockOutbound*` - Messages from agent to customer
+   - `messageInput*` - Input field and send button
+
+## Important Notes
+
+- You do NOT need to provide all tokens - only override the ones you want to change
+- Token values are CSS strings (e.g., `"#FF0000"`, `"16px"`, `"bold"`)
+- Invalid token names are silently ignored
+- The component uses default values for any tokens you don't specify

package/skills/managing-webapp-agentforce-conversation-client/references/troubleshooting.md

@@ -0,0 +1,57 @@
+# Troubleshooting
+
+Common issues when using the Agentforce Conversation Client.
+
+---
+
+### Component throws "requires agentId"
+
+**Cause:** `agentId` was not passed.
+
+**Solution:** Pass `agentId` directly as a flat prop:
+
+```tsx
+<AgentforceConversationClient agentId="0Xx000000000000AAA" />
+```
+
+---
+
+### Chat widget does not appear
+
+**Cause:** Invalid `agentId` or inactive agent.
+
+**Solution:**
+
+1. Confirm the id is correct (18-char Salesforce id, starts with `0Xx`).
+2. Ensure the agent is Active in **Setup → Agentforce Agents**.
+3. Verify the agent is deployed to the target channel.
+
+---
+
+### Authentication error on localhost
+
+**Cause:** `localhost:<PORT>` is not trusted for inline frames.
+
+**Solution:**
+
+1. Go to **Setup → Session Settings → Trusted Domains for Inline Frames**.
+2. Add `localhost:<PORT>` (example: `localhost:3000`).
+
+**Important:**
+
+- This setting should be **temporary for local development only**.
+- **Remove `localhost:<PORT>` from trusted domains after development**.
+- **Recommended:** Test the Agentforce conversation client in a deployed app instead of relying on localhost trusted domains for extended periods.
+
+---
+
+### Blank iframe / auth session issues
+
+**Possible cause:** First-party Salesforce cookie restriction may block embedded auth flow in some environments.
+
+**Solution:**
+
+1. Go to **Setup → Session Settings**.
+2. Find **Require first party use of Salesforce cookies**.
+3. Disable it **only if needed and approved by your security/admin team**.
+4. Save and reload.

package/skills/switching-org/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: switching-org
+description: Switches the active Salesforce org (default target-org) using the Salesforce CLI. Use whenever someone wants to change which org CLI commands run against — whether they say "switch org", "change default org", "set my org to", "use alias", "point to", or describe wanting to work against a specific org, scratch org, sandbox, or production.
+compatibility: Salesforce CLI (sf) v2+
+metadata:
+  version: "1.0"
+---
+
+## Steps
+
+1. Identify the org: the user provides a username or alias (`orgIdentifier`). If not provided, run `sf org list` to show authenticated orgs and ask the user which one to use.
+2. Set the default org:
+   - Local (default): `sf config set target-org <orgIdentifier>`
+     - Applies only within the current project directory. Use this for normal project work.
+   - Global (only if user explicitly requests): `sf config set target-org <orgIdentifier> --global`
+     - Applies system-wide across all directories. Use when working outside a project or when the user asks for global scope.
+   - If this fails, report the error and suggest running `sf org login web` if the org may not be authorized.
+3. Verify:
+   - `sf config get target-org --json`
+   - Note: the JSON output does not include a scope/location field — it cannot confirm whether the value is local or global. Confirm the value only, e.g.: `target-org is now set to: <value>`
+   - If it fails, report the error and advise running `sf config get target-org`.
+
+## Notes
+
+- Unified CLI uses keys like `target-org` and `target-dev-hub`. Legacy sfdx keys (`defaultusername`, `defaultdevhubusername`) are deprecated in this context.
+- The sf CLI does not have `--local` or `--scope` flags for config set. Local scope is the default behavior.
+- If the org does not change after setting the config, check whether `SF_TARGET_ORG` is set — environment variables override config values.
+- Salesforce CLI config (unified) reference: https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_config_commands_unified.htm#cli_reference_config_set_unified

package/skills/using-webapp-graphql/SKILL.md

@@ -0,0 +1,324 @@
+---
+name: using-webapp-graphql
+description: Salesforce GraphQL data access. Use when the user asks to fetch, query, or mutate Salesforce data, or add a GraphQL operation for an object like Account, Contact, or Opportunity.
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.graphql"
+---
+
+# Salesforce GraphQL
+
+Guidance for querying and mutating Salesforce data via the Salesforce GraphQL API. Use `createDataSDK()` + `sdk.graphql?.()` and codegen tooling.
+
+## When to Use
+
+- User asks to "fetch data from Salesforce"
+- User asks to "query" or "mutate" Salesforce records
+- User wants to add a new GraphQL operation (query or mutation)
+- User asks to add data access for a Salesforce object (Account, Contact, Opportunity, etc.)
+
+## Schema Access Policy (GREP ONLY)
+
+> **GREP ONLY** — The `schema.graphql` file is very large (~265,000+ lines). All schema lookups **MUST** use the grep-only commands defined in the `exploring-graphql-schema` skill. Do NOT open, read, stream, or parse `./schema.graphql` with any tool other than grep.
+
+## Directory Context
+
+The generated app has a two-level directory structure. Commands must run from the correct directory.
+
+```
+<project-root>/                                            ← SFDX project root
+├── schema.graphql                                         ← grep target
+├── sfdx-project.json
+└── force-app/main/default/webapplications/<app-name>/     ← webapp dir
+    ├── package.json         (npm scripts: graphql:schema, graphql:codegen, lint)
+    ├── eslint.config.js     (schema ref: ../../../../../schema.graphql)
+    ├── codegen.yml          (schema ref: ../../../../../schema.graphql)
+    └── src/                 (source code, .graphql query files)
+```
+
+| Command                   | Run from         | Why                                    |
+| ------------------------- | ---------------- | -------------------------------------- |
+| `npm run graphql:schema`  | **webapp dir**   | Script is in webapp's `package.json`   |
+| `npm run graphql:codegen` | **webapp dir**   | Reads `codegen.yml` in webapp dir       |
+| `npx eslint <file>`      | **webapp dir**   | Reads `eslint.config.js` in webapp dir |
+| `grep ... schema.graphql` | **project root** | `schema.graphql` lives at project root |
+| `sf api request graphql` | **project root** | Needs `sfdx-project.json`              |
+
+> **Wrong directory = silent failures.** `npm run graphql:schema` from the project root will fail with "missing script." `grep ./schema.graphql` from the webapp dir will fail with "no such file."
+
+## Prerequisites
+
+The base React app (`base-react-app`) ships with all GraphQL dependencies and tooling pre-configured:
+
+- `@salesforce/sdk-data` — runtime SDK for `createDataSDK` and `gql`
+- `@graphql-codegen/cli` + plugins — type generation from `.graphql` files and inline `gql` queries
+- `@graphql-eslint/eslint-plugin` — validates `.graphql` files and `gql` template literals against `schema.graphql` (used as a query validation gate — see Step 6)
+- `graphql` — shared by codegen, ESLint, and schema introspection
+
+Before using this skill, ensure:
+
+1. The `@salesforce/sdk-data` package is available (provides `createDataSDK`, `gql`, `NodeOfConnection`)
+2. **Deployment order**: Metadata must be deployed before schema fetch; schema must be refetched after any metadata deployment. Invoke the `deploying-to-salesforce` skill when deploying or syncing with the org.
+3. A `schema.graphql` file exists at the project root. If missing, generate it:
+   ```bash
+   # Run from webapp dir (force-app/main/default/webapplications/<app-name>/)
+   npm run graphql:schema
+   ```
+
+## npm Scripts
+
+- **`npm run graphql:schema`** — _(run from webapp dir)_ Downloads the full GraphQL schema from a connected Salesforce org via introspection. Outputs `schema.graphql` to the project root.
+- **`npm run graphql:codegen`** — _(run from webapp dir)_ Generates TypeScript types from `.graphql` files and inline `gql` queries. Outputs to `src/api/graphql-operations-types.ts`.
+
+## Workflow
+
+### Step 1: Download Schema
+
+Ensure `schema.graphql` exists at the project root. If missing, run `npm run graphql:schema` from the webapp dir.
+
+### Step 2: Explore the Schema (grep-only)
+
+Before writing any query, verify the target object and its fields exist in the schema.
+
+**Invoke the `exploring-graphql-schema` skill** for the full exploration workflow and **mandatory grep-only access policy**.
+
+> **GREP ONLY** — All schema lookups MUST use the grep commands defined in the `exploring-graphql-schema` skill. Do NOT open, read, stream, or parse `./schema.graphql` with any tool other than grep.
+
+Key actions (all via grep):
+
+- `type <ObjectName> implements Record` — find available fields
+- `input <ObjectName>_Filter` — find filter options
+- `input <ObjectName>_OrderBy` — find sorting options
+- `input <ObjectName>CreateInput` / `<ObjectName>UpdateInput` — find mutation input types
+
+### Step 3: Choose the Query Pattern
+
+**Pattern 1 — External `.graphql` file** (recommended for complex queries):
+
+- Queries with variables, fragments, or shared across files
+- Full codegen support, syntax highlighting, shareable
+- Requires codegen step after changes
+- See example: `api/utils/accounts.ts` + `api/utils/query/highRevenueAccountsQuery.graphql`
+
+**Pattern 2 — Inline `gql` tag** (recommended for simple queries):
+
+- Simple queries without variables; colocated with usage code
+- Supports dynamic queries (field set varies at runtime)
+- **MUST use `gql` tag** — plain template strings bypass `@graphql-eslint` validation
+- See example: `api/utils/user.ts`
+
+### Step 4: Write the Query
+
+For **Pattern 1**:
+
+1. Create a `.graphql` file under `src/api/utils/query/`
+2. Follow UIAPI structure: `query { uiapi { query { ObjectName(...) { edges { node { ... } } } } } }`
+3. For mutations, invoke the `generating-graphql-mutation-query` skill
+4. For read queries, invoke the `generating-graphql-read-query` skill
+
+For **Pattern 2**:
+
+1. Define query inline using the `gql` template tag
+2. Ensure the query name matches what codegen expects
+
+### Step 5: Test Queries Against Live Org
+
+Use the testing workflows in the `generating-graphql-read-query` and `generating-graphql-mutation-query` skills to validate queries against the connected org before integrating into the app.
+
+### Step 6: Generate Types
+
+```bash
+# Run from webapp dir (force-app/main/default/webapplications/<app-name>/)
+npm run graphql:codegen
+```
+
+This updates `src/api/graphql-operations-types.ts` with `<OperationName>Query`/`<OperationName>Mutation` and `<OperationName>QueryVariables`/`<OperationName>MutationVariables`.
+
+### Step 7: Lint Validate
+
+Run ESLint on the file containing the query to validate it against the schema **before** any live testing:
+
+```bash
+# Run from webapp dir
+npx eslint <path-to-file>
+```
+
+The `@graphql-eslint/eslint-plugin` processor extracts GraphQL from `gql` template literals and validates them against `schema.graphql`. Fix all ESLint errors before proceeding.
+
+### Step 8: Implement and Verify
+
+Implement the data access function using the pattern below. Use the Quality Checklist before completing.
+
+---
+
+## Core Types & Function Signatures
+
+### createDataSDK and graphql
+
+```typescript
+import { createDataSDK } from "@salesforce/sdk-data";
+
+const sdk = await createDataSDK();
+const response = await sdk.graphql?.<ResponseType, VariablesType>(query, variables);
+```
+
+`createDataSDK()` returns a `DataSDK` instance. The `graphql` method uses optional chaining (`?.`) because not all surfaces support GraphQL.
+
+### gql Template Tag
+
+```typescript
+import { gql } from "@salesforce/sdk-data";
+
+const MY_QUERY = gql`
+  query MyQuery {
+    uiapi { ... }
+  }
+`;
+```
+
+The `gql` tag enables ESLint validation against the schema. Plain template strings bypass validation.
+
+### Error Handling
+
+Default: treat any errors as failure (Strategy A). For partial data tolerance, log errors but use data. For mutations where some return fields are inaccessible, use Strategy C (fail only when no data).
+
+```typescript
+// Default: strict
+if (response?.errors?.length) {
+  throw new Error(response.errors.map((e) => e.message).join("; "));
+}
+const result = response?.data;
+```
+
+Responses follow `uiapi.query.ObjectName.edges[].node`; fields use `{ value }`.
+
+### NodeOfConnection
+
+```typescript
+import { type NodeOfConnection } from "@salesforce/sdk-data";
+
+type AccountNode = NodeOfConnection<GetHighRevenueAccountsQuery["uiapi"]["query"]["Account"]>;
+```
+
+---
+
+## Pattern 1: External .graphql File
+
+Create a `.graphql` file, run `npm run graphql:codegen`, import with `?raw` suffix, and use generated types.
+
+**Required imports:**
+
+```typescript
+import { createDataSDK, type NodeOfConnection } from "@salesforce/sdk-data";
+import MY_QUERY from "./query/myQuery.graphql?raw"; // ← ?raw suffix required
+import type { GetMyDataQuery, GetMyDataQueryVariables } from "../graphql-operations-types";
+```
+
+**When to use:** Complex queries with variables, fragments, or shared across files. Does NOT support dynamic queries (field set varies at runtime).
+
+---
+
+## Pattern 2: Inline gql Tag
+
+**Required imports:**
+
+```typescript
+import { createDataSDK, gql } from "@salesforce/sdk-data";
+import { type CurrentUserQuery } from "../graphql-operations-types";
+
+const MY_QUERY = gql`
+  query CurrentUser {
+    uiapi { ... }
+  }
+`;
+```
+
+> **MUST use `gql` tag** — plain template strings bypass the `@graphql-eslint` processor entirely, meaning no lint validation against the schema.
+
+**When to use:** Simple, colocated queries. Supports dynamic queries (field set varies at runtime).
+
+---
+
+## Conditional Field Selection
+
+For dynamic fieldsets with **known** fields, use `@include(if: $condition)` and `@skip(if: $condition)` in `.graphql` files. See GraphQL spec for details.
+
+---
+
+## Anti-Patterns (Not Recommended)
+
+### Direct API Calls
+
+```typescript
+// NOT RECOMMENDED: Direct axios/fetch calls for GraphQL
+// PREFERRED: Use the Data SDK
+const sdk = await createDataSDK();
+const response = await sdk.graphql?.<ResponseType>(query, variables);
+```
+
+### Missing Type Definitions
+
+```typescript
+// NOT RECOMMENDED: Untyped GraphQL calls
+// PREFERRED: Provide response type
+const response = await sdk.graphql?.<GetMyDataQuery>(query);
+```
+
+### Plain String Queries (Without gql Tag)
+
+```typescript
+// NOT RECOMMENDED: Plain strings bypass ESLint validation
+const query = `query { ... }`;
+
+// PREFERRED: Use gql tag for inline queries
+const QUERY = gql`query { ... }`;
+```
+
+---
+
+## Quality Checklist
+
+> If you have not completed the workflow above, **stop and complete it first**. Invoke the skill workflow before using this checklist.
+
+Before completing GraphQL data access code:
+
+### For Pattern 1 (.graphql files):
+
+1. [ ] All field names verified via grep against `schema.graphql` (invoke `exploring-graphql-schema`)
+2. [ ] Create `.graphql` file for the query/mutation
+3. [ ] Run `npm run graphql:codegen` to generate types
+4. [ ] Import query with `?raw` suffix
+5. [ ] Import generated types from `graphql-operations-types.ts`
+6. [ ] Use `sdk.graphql?.<ResponseType>()` with proper generic
+7. [ ] Handle `response.errors` and destructure `response.data`
+8. [ ] Use `NodeOfConnection` for cleaner node types when needed
+9. [ ] Run `npx eslint <file>` from webapp dir — fix all GraphQL errors
+
+### For Pattern 2 (inline with gql):
+
+1. [ ] All field names verified via grep against `schema.graphql`
+2. [ ] Define query using `gql` template tag (NOT a plain string)
+3. [ ] Ensure query name matches generated types in `graphql-operations-types.ts`
+4. [ ] Import generated types for the query
+5. [ ] Use `sdk.graphql?.<ResponseType>()` with proper generic
+6. [ ] Handle `response.errors` and destructure `response.data`
+7. [ ] Run `npx eslint <file>` from webapp dir — fix all GraphQL errors
+
+### General:
+
+- [ ] Lint validation passes (`npx eslint <file>` reports no GraphQL errors)
+- [ ] Query field names match the schema exactly (case-sensitive, confirmed via grep)
+- [ ] Response type generic is provided to `sdk.graphql?.<T>()`
+- [ ] Optional chaining is used for nested response data
+
+---
+
+## Reference
+
+- Schema exploration: invoke the `exploring-graphql-schema` skill
+- Read query generation: invoke the `generating-graphql-read-query` skill
+- Mutation query generation: invoke the `generating-graphql-mutation-query` skill
+- Shared GraphQL schema types: `shared-schema.graphqls` (in this skill directory)
+- Schema download: `npm run graphql:schema` (run from webapp dir)
+- Type generation: `npm run graphql:codegen` (run from webapp dir)