@salesforce/afv-skills 1.1.0 → 1.3.0

package/skills/generating-webapp-graphql-read-query/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: generating-webapp-graphql-read-query
+description: Generate Salesforce GraphQL read queries. Use when the query to generate is a read query. Schema exploration must complete first — invoke exploring-graphql-schema first.
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.graphql"
+---
+
+# Salesforce GraphQL Read Query Generation
+
+**Triggering conditions**
+
+1. Only if the schema exploration phase completed successfully (invoke `exploring-graphql-schema` first)
+2. Only if the query to generate is a read query
+
+## Schema Access Policy
+
+> ⚠️ **GREP ONLY** — During query generation you may need to verify field names, types, or relationships. 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.
+
+## Field-Level Security and @optional
+
+Field-level security (FLS) restricts which fields different users can see. Use the `@optional` directive on Salesforce record fields when possible. The server omits the field when the user lacks access, allowing the query to succeed instead of failing. Apply `@optional` to scalar fields, value-type fields (e.g. `Name { value }`), parent relationships, and child relationships. Available in API v65.0+.
+
+**Consuming code must defend against missing fields.** When a field is omitted due to FLS, it will be `undefined` (or absent) in the response. Use optional chaining (`?.`), nullish coalescing (`??`), and explicit null/undefined checks when reading query results. Never assume an optional field is present — otherwise the app may crash or behave incorrectly for users without field access.
+
+```ts
+// ✅ Defend against missing fields
+const name = node.Name?.value ?? '';
+const relatedName = node.RelationshipName?.Name?.value ?? 'N/A';
+
+// ❌ Unsafe — will throw if field omitted due to FLS
+const name = node.Name.value;
+```
+
+## Your Role
+
+You are a GraphQL expert. Generate Salesforce-compatible read queries. Schema exploration must complete first. If the schema exploration has not been executed yet, you **MUST** run the full exploration workflow from the `exploring-graphql-schema` skill first, then return here for read query generation.
+
+## Read Query Generation Workflow
+
+Strictly follow the rules below when generating the GraphQL read query:
+
+1. **No Proliferation** - Only generate for the explicitly requested fields, nothing else. Do NOT add fields the user did not ask for.
+2. **Unique Query** - Leverage child relationships to query entities in one single query
+3. **Navigate Entities** - Always use `relationshipName` to access reference fields and child entities
+   1. **Exception** - if the `relationshipName` field is null, you can't navigate the related entity, and will have to return the `Id` itself
+4. **Leverage Fragments** - Generate one fragment per possible type on polymorphic fields (field with `dataType="REFERENCE"` and more than one entry in `referenceToInfos` introspection attribute)
+5. **Type Consistency** - Make sure variables used as query arguments and their related fields share the same GraphQL type. Verify types against grep output from the schema — do not assume types
+6. **Type Enforcement** - Make sure to leverage field type information from introspection and GraphQL schema to generate field access
+7. **Field Name Validation** - Every field name in the generated query **MUST** match a field confirmed via grep lookup in the schema. Do NOT guess or assume field names exist
+8. **@optional for FLS** - Apply `@optional` on all Salesforce record fields when possible (see [Field-Level Security and @optional](#field-level-security-and-optional)). This lets the query succeed when the user lacks field-level access; the server omits inaccessible fields instead of failing
+9. **Consuming code defense** - When generating or modifying code that consumes read query results, defend against missing fields (see [Field-Level Security and @optional](#field-level-security-and-optional)). Use optional chaining, nullish coalescing, and null/undefined checks — never assume optional fields are present
+10. **Semi and anti joins** - Use the semi-join or anti-join templates to filter an entity with conditions on child entities
+11. **Query Generation** - Use the [template](#read-query-template) to generate the query
+12. **Output Format** - Use the [standalone](#read-standalone-default-output-format---clean-code-only)
+13. **Lint Validation** - After writing the query to a file, run `npx eslint <file>` from the webapp dir to validate it against the schema. Fix any reported errors before proceeding. See [Lint Validation](#lint-validation) for details
+14. **Test the Query** - Use the [Generated Read Query Testing](#generated-read-query-testing) workflow to test the generated query
+    1. **Report First** - Always output the generated query in the proper output format BEFORE initiating any test
+
+## Read Query Template
+
+```graphql
+query QueryName {
+  uiapi {
+    query {
+      EntityName(
+        # conditions here
+      ) {
+        edges {
+          node {
+            # Direct fields — use @optional for FLS resilience
+            FieldName @optional { value }
+
+            # Non-polymorphic reference (single type)
+            RelationshipName @optional {
+              Id
+              Name { value }
+            }
+
+            # Polymorphic reference (multiple types)
+            PolymorphicRelationshipName @optional {
+              ...TypeAInfo
+              ...TypeBInfo
+            }
+
+            # Child relationship (subquery)
+            RelationshipName @optional (
+              # conditions here
+            ) {
+              edges {
+                node {
+                  # fields
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+
+fragment TypeAInfo on TypeA {
+  Id
+  SpecificFieldA @optional { value }
+}
+
+fragment TypeBInfo on TypeB {
+  Id
+  SpecificFieldB @optional { value }
+}
+```
+
+## Semi-Join and Anti-Join Condition Template
+
+Semi-joins (resp. anti-joins) condition leverage parent-child relationships and allow filtering the parent entity using a condition on child entities.
+This is a standard `where` condition, on the parent entity's `Id`, expressed using the `inq` (resp. `ninq`, i.e. not `inq`) operator. This operator accepts two attributes:
+
+- The child entity camelcase name to apply the condition on, with a value expressing the condition
+- The field name on the child entity containing the parent entity `Id`, which is the `fieldName` from the `childRelationships` information for the child entity
+- If the only condition is related child entity existence, you can use an `Id: { ne: null }` condition
+
+### Semi-Join Example - ParentEntity with at least one Matching ChildEntity
+
+```graphql
+query testSemiJoin {
+  uiapi {
+    query {
+      ParentEntity(
+        where: {
+          Id: {
+            inq: {
+              ChildEntity: {
+                # standard conditions here
+                Name: { like: "test%" }
+                Type: { eq: "some value" }
+              }
+              ApiName: "parentIdFieldInChild"
+            }
+          }
+        }
+      ) {
+        edges {
+          node {
+            Id
+            Name @optional {
+              value
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Anti-Join Example - ParentEntity with no Matching ChildEntity
+
+Same example as the [Semi-Join Example](#semi-join-example---parententity-with-at-least-one-matching-childentity), but replacing the `inq` operator by the `ninq` one.
+
+## Read Standalone (Default) Output Format - CLEAN CODE ONLY
+
+```javascript
+const QUERY_NAME = `
+  query GetData {
+    # query here
+  }
+`;
+
+const QUERY_VARIABLES = {
+  // variables here
+};
+```
+
+**❌ FORBIDDEN — Do NOT include any of the following:**
+
+- Explanatory comments about the query (inline or surrounding)
+- Field descriptions or annotations
+- Additional text about what the query does
+- Workflow step descriptions or summaries
+- Comments like `// fetches...`, `// returns...`, `/* ... */`
+
+**✅ ONLY output:**
+
+- The raw query string constant
+- The variables object constant
+- Nothing else — no imports, no exports, no wrapper functions
+
+## Lint Validation
+
+After writing the generated query into a source file, validate it against the schema using the project's GraphQL ESLint setup:
+
+```bash
+# Run from webapp dir (force-app/main/default/webapplications/<app-name>/)
+npx eslint <path-to-file-containing-query>
+```
+
+**How it works:** The ESLint config uses `@graphql-eslint/eslint-plugin` with its `processor`, which extracts GraphQL operations from `gql` template literals in `.ts`/`.tsx` files and validates the extracted `.graphql` virtual files against `schema.graphql`.
+
+**Rules enforced:** `no-anonymous-operations`, `no-duplicate-fields`, `known-fragment-names`, `no-undefined-variables`, `no-unused-variables`
+
+**On failure:** Fix the reported issues, re-run `npx eslint <file>` until clean, then proceed to testing.
+
+> ⚠️ **Prerequisites**: The `schema.graphql` file must exist (invoke `exploring-graphql-schema` first) and project dependencies must be installed (`npm install`).
+
+## Generated Read Query Testing
+
+**Triggering conditions** — **ALL conditions must be true:**
+
+1. The [Read Query Generation Workflow](#read-query-generation-workflow) completed with status `SUCCESS` and you have a generated query
+2. The query is a read query
+3. A non-manual method was used during schema exploration to retrieve introspection data
+
+**Workflow**
+
+1. **Report Step** - State the exact method you will use to test (e.g., `sf api request graphql` from the **project root**, Connect API, etc.) — this **MUST** match the method used during schema exploration
+2. **Interactive Step** - Ask the user whether they want you to test the query using the proposed method
+   1. **STOP and WAIT** for the user's answer. Do NOT proceed until the user responds. Do NOT assume consent.
+3. **Test Query** - Only if the user explicitly agrees:
+   1. Use `sf api request rest` to POST the query to the GraphQL endpoint:
+      ```bash
+      sf api request rest /services/data/v65.0/graphql \
+        --method POST \
+        --body '{"query":"query GetData { uiapi { query { EntityName { edges { node { Id } } } } } }"}'
+      ```
+   2. Replace `v65.0` with the API version of the target org
+   3. Replace the `query` value with the generated read query string
+   4. If the query uses variables, include them in the JSON body as a `variables` key
+   5. Report the result as `SUCCESS` if the query executed without error, or `FAILED` if errors were returned
+   6. An empty result set with no errors is `SUCCESS` — the query is valid, the org simply has no matching data
+4. **Remediation Step** - If status is `FAILED`, use the [`FAILED` status handling workflows](#failed-status-handling-workflow)
+
+### `FAILED` Status Handling Workflow
+
+The query is invalid:
+
+1. **Error Analysis** - Parse and categorize the specific error messages
+2. **Root Cause Identification** - Use error message to identify the root cause:
+   - **Syntax** - Error contains `invalid syntax`
+   - **Validation** - Error contains `validation error`
+   - **Type** - Error contains `VariableTypeMismatch` or `UnknownType`
+3. **Targeted Resolution** - Depending on the root cause categorization
+   - **Syntax** - Update the query using the error message information to fix the syntax errors
+   - **Validation** - The field name is most probably invalid. Re-run the relevant grep command from the `exploring-graphql-schema` skill to verify the correct field name. If still unclear, ask the user for clarification and **STOP and WAIT** for their answer
+   - **Type** - Use the error details and re-verify the type via grep lookup in the schema. Correct the argument type and adjust variables accordingly
+4. **Test Again** - Resume the [query testing workflow](#generated-read-query-testing) with the updated query (increment and track attempt counter)
+5. **Escalation Path** - If targeted resolution fails after 2 attempts, ask for additional details and restart the entire GraphQL workflow from the `exploring-graphql-schema` skill
+
+## Related Skills
+
+- Schema exploration: `exploring-graphql-schema` (must complete first)
+- Mutation generation: `generating-graphql-mutation-query`

package/skills/implementing-webapp-file-upload/SKILL.md

@@ -0,0 +1,396 @@
+---
+name: implementing-webapp-file-upload
+description: Add file upload functionality to React webapps with progress tracking and Salesforce ContentVersion integration. Use when the user wants to upload files, attach documents, handle file input, create file dropzones, track upload progress, or link files to Salesforce records. This feature provides programmatic APIs ONLY — no components or hooks are exported. Build your own custom UI using the upload() API. ALWAYS use this feature instead of building file upload from scratch with FormData or XHR.
+---
+
+# File Upload API (workflow)
+
+When the user wants file upload functionality in a React webapp, follow this workflow. This feature provides **APIs only** — you must build the UI components yourself using the provided APIs.
+
+## CRITICAL: This is an API-only package
+
+The package exports **programmatic APIs**, not React components or hooks. You will:
+
+- Use the `upload()` function to handle file uploads with progress tracking
+- Build your own custom UI (file input, dropzone, progress bars, etc.)
+- Track upload progress through the `onProgress` callback
+
+**Do NOT:**
+
+- Expect pre-built components like `<FileUpload />` — they are not exported
+- Try to import React hooks like `useFileUpload` — they are not exported
+- Look for dropzone components — they are not exported
+
+The source code contains reference components for demonstration, but they are **not available** as imports. Use them as examples to build your own UI.
+
+## 1. Install the package
+
+```bash
+npm install @salesforce/webapp-template-feature-react-file-upload-experimental
+```
+
+Dependencies are automatically installed:
+
+- `@salesforce/webapp-experimental` (API client)
+- `@salesforce/sdk-data` (data SDK)
+
+## 2. Understand the three upload patterns
+
+### Pattern A: Basic upload (no record linking)
+
+Upload files to Salesforce and get back `contentBodyId` for each file. No ContentVersion record is created.
+
+**When to use:**
+
+- User wants to upload files first, then create/link them to a record later
+- Building a multi-step form where the record doesn't exist yet
+- Deferred record linking scenarios
+
+```tsx
+import { upload } from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+
+const results = await upload({
+  files: [file1, file2],
+  onProgress: (progress) => {
+    console.log(`${progress.fileName}: ${progress.status} - ${progress.progress}%`);
+  },
+});
+
+// results[0].contentBodyId: "069..." (always available)
+// results[0].contentVersionId: undefined (no record linked)
+```
+
+### Pattern B: Upload with immediate record linking
+
+Upload files and immediately link them to an existing Salesforce record by creating ContentVersion records.
+
+**When to use:**
+
+- Record already exists (Account, Opportunity, Case, etc.)
+- User wants files immediately attached to the record
+- Direct upload-and-attach scenarios
+
+```tsx
+import { upload } from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+
+const results = await upload({
+  files: [file1, file2],
+  recordId: "001xx000000yyyy", // Existing record ID
+  onProgress: (progress) => {
+    console.log(`${progress.fileName}: ${progress.status} - ${progress.progress}%`);
+  },
+});
+
+// results[0].contentBodyId: "069..." (always available)
+// results[0].contentVersionId: "068..." (linked to record)
+```
+
+### Pattern C: Deferred record linking (record creation flow)
+
+Upload files without a record, then link them after the record is created.
+
+**When to use:**
+
+- Building a "create record with attachments" form
+- Record doesn't exist until form submission
+- Need to upload files before knowing the final record ID
+
+```tsx
+import {
+  upload,
+  createContentVersion,
+} from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+
+// Step 1: Upload files (no recordId)
+const uploadResults = await upload({
+  files: [file1, file2],
+  onProgress: (progress) => console.log(progress),
+});
+
+// Step 2: Create the record
+const newRecordId = await createRecord(formData);
+
+// Step 3: Link uploaded files to the new record
+for (const file of uploadResults) {
+  const contentVersionId = await createContentVersion(
+    new File([""], file.fileName),
+    file.contentBodyId,
+    newRecordId,
+  );
+}
+```
+
+## 3. Build your custom UI
+
+The package provides the backend — you build the frontend. Here's a minimal example:
+
+```tsx
+import {
+  upload,
+  type FileUploadProgress,
+} from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+import { useState } from "react";
+
+function CustomFileUpload({ recordId }: { recordId?: string }) {
+  const [progress, setProgress] = useState<Map<string, FileUploadProgress>>(new Map());
+
+  const handleFileSelect = async (event: React.ChangeEvent<HTMLInputElement>) => {
+    const files = Array.from(event.target.files || []);
+
+    await upload({
+      files,
+      recordId,
+      onProgress: (fileProgress) => {
+        setProgress((prev) => new Map(prev).set(fileProgress.fileName, fileProgress));
+      },
+    });
+  };
+
+  return (
+    <div>
+      <input type="file" multiple onChange={handleFileSelect} />
+
+      {Array.from(progress.entries()).map(([fileName, fileProgress]) => (
+        <div key={fileName}>
+          {fileName}: {fileProgress.status} - {fileProgress.progress}%
+          {fileProgress.error && <span>Error: {fileProgress.error}</span>}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## 4. Track upload progress
+
+The `onProgress` callback fires multiple times for each file as it moves through stages:
+
+| Status         | When                                           | Progress Value       |
+| -------------- | ---------------------------------------------- | -------------------- |
+| `"pending"`    | File queued for upload                         | `0`                  |
+| `"uploading"`  | Upload in progress (XHR)                       | `0-100` (percentage) |
+| `"processing"` | Creating ContentVersion (if recordId provided) | `0`                  |
+| `"success"`    | Upload complete                                | `100`                |
+| `"error"`      | Upload failed                                  | `0`                  |
+
+**Always provide visual feedback:**
+
+- Show file name
+- Display current status
+- Render progress bar for "uploading" status
+- Show error message if status is "error"
+
+## 5. Cancel uploads (optional)
+
+Use an `AbortController` to allow users to cancel uploads:
+
+```tsx
+const abortController = new AbortController();
+
+const handleUpload = async (files: File[]) => {
+  try {
+    await upload({
+      files,
+      signal: abortController.signal,
+      onProgress: (progress) => console.log(progress),
+    });
+  } catch (error) {
+    console.error("Upload cancelled or failed:", error);
+  }
+};
+
+const cancelUpload = () => {
+  abortController.abort();
+};
+```
+
+## 6. Link to current user (special case)
+
+If the user wants to upload files to their own profile or personal library:
+
+```tsx
+import {
+  upload,
+  getCurrentUserId,
+} from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+
+const userId = await getCurrentUserId();
+await upload({ files, recordId: userId });
+```
+
+## API Reference
+
+### upload(options)
+
+Main upload API that handles complete flow with progress tracking.
+
+```typescript
+interface UploadOptions {
+  files: File[];
+  recordId?: string | null; // If provided, creates ContentVersion
+  onProgress?: (progress: FileUploadProgress) => void;
+  signal?: AbortSignal; // Optional cancellation
+}
+
+interface FileUploadProgress {
+  fileName: string;
+  status: "pending" | "uploading" | "processing" | "success" | "error";
+  progress: number; // 0-100 for uploading, 0 for other states
+  error?: string;
+}
+
+interface FileUploadResult {
+  fileName: string;
+  size: number;
+  contentBodyId: string; // Always available
+  contentVersionId?: string; // Only if recordId was provided
+}
+```
+
+**Returns:** `Promise<FileUploadResult[]>`
+
+### createContentVersion(file, contentBodyId, recordId)
+
+Manually create a ContentVersion record from a previously uploaded file.
+
+```typescript
+async function createContentVersion(
+  file: File,
+  contentBodyId: string,
+  recordId: string,
+): Promise<string | undefined>;
+```
+
+**Parameters:**
+
+- `file` — File object (used for metadata like name)
+- `contentBodyId` — ContentBody ID from previous upload
+- `recordId` — Record ID for FirstPublishLocationId
+
+**Returns:** ContentVersion ID if successful
+
+### getCurrentUserId()
+
+Get the current user's Salesforce ID.
+
+```typescript
+async function getCurrentUserId(): Promise<string>;
+```
+
+**Returns:** Current user ID
+
+## Common UI patterns
+
+### File input with button
+
+```tsx
+<input type="file" multiple accept=".pdf,.doc,.docx,.jpg,.png" onChange={handleFileSelect} />
+```
+
+### Drag-and-drop zone
+
+Build your own dropzone using native events:
+
+```tsx
+function DropZone({ onDrop }: { onDrop: (files: File[]) => void }) {
+  const handleDrop = (e: React.DragEvent) => {
+    e.preventDefault();
+    const files = Array.from(e.dataTransfer.files);
+    onDrop(files);
+  };
+
+  return (
+    <div
+      onDrop={handleDrop}
+      onDragOver={(e) => e.preventDefault()}
+      style={{ border: "2px dashed #ccc", padding: "2rem" }}
+    >
+      Drop files here
+    </div>
+  );
+}
+```
+
+### Progress bar
+
+```tsx
+{
+  progress.status === "uploading" && (
+    <div style={{ width: "100%", background: "#eee" }}>
+      <div
+        style={{
+          width: `${progress.progress}%`,
+          background: "#0176d3",
+          height: "8px",
+        }}
+      />
+    </div>
+  );
+}
+```
+
+## Decision tree for agents
+
+**User asks for file upload functionality:**
+
+1. **Ask about record context:**
+   - "Do you want to link uploaded files to a specific record, or upload them first and link later?"
+
+2. **Based on response:**
+   - **Link to existing record** → Use Pattern B with `recordId`
+   - **Upload first, link later** → Use Pattern A (no recordId), then Pattern C for linking
+   - **Link to current user** → Use Pattern B with `getCurrentUserId()`
+
+3. **Build the UI:**
+   - Create file input or dropzone (not provided by package)
+   - Add progress display for each file (status + progress bar)
+   - Handle errors in the UI
+
+4. **Test the implementation:**
+   - Verify progress callbacks fire correctly
+   - Check that `contentBodyId` is returned
+   - If `recordId` was provided, verify `contentVersionId` is returned
+
+## Reference implementation
+
+The package includes a reference implementation in `src/features/fileupload/` with:
+
+- `FileUpload.tsx` — Complete component with dropzone and dialog
+- `FileUploadDialog.tsx` — Progress tracking dialog
+- `FileUploadDropZone.tsx` — Drag-and-drop zone
+- `useFileUpload.ts` — React hook for state management
+
+**These are NOT exported** but can be viewed as examples. Read the source files to understand patterns for building your own UI.
+
+## Troubleshooting
+
+**Upload fails with CORS error:**
+
+- Ensure the webapp is properly deployed to Salesforce or running on `localhost`
+- Check that the org allows the origin in CORS settings
+
+**No progress updates:**
+
+- Verify `onProgress` callback is provided
+- Check that the callback function updates React state correctly
+
+**ContentVersion not created:**
+
+- Verify `recordId` is provided to `upload()` function
+- Check that the record ID is valid and exists in the org
+- Ensure user has permissions to create ContentVersion records
+
+**Files upload but don't appear in record:**
+
+- Verify `recordId` is correct
+- Check that ContentVersion was created (look for `contentVersionId` in results)
+- Confirm user has access to view files on the record
+
+## DO NOT do these things
+
+- ❌ Build XHR/fetch upload logic from scratch — use the `upload()` API
+- ❌ Try to import `<FileUpload />` component — it's not exported
+- ❌ Try to import `useFileUpload` hook — it's not exported
+- ❌ Use third-party file upload libraries when this feature exists
+- ❌ Skip progress tracking — always provide user feedback
+- ❌ Ignore errors — always handle and display error messages