@salesforce/webapp-template-feature-graphql-experimental 1.56.0 → 1.57.0

package/README.md

@@ -15,7 +15,7 @@ The base React app (`@salesforce/webapp-template-base-react-app-experimental`) i
 - `@salesforce/sdk-data` dependency
 - GraphQL ESLint plugin and rules
 - GraphQL codegen dependencies and configuration (`codegen.yml`)
-- `executeGraphQL<T>()` utility and `gql` template tag
+- `getDataSDK()` + `data.graphql?.()` pattern and `gql` template tag
 - Example components: `AccountsTable`, `AccountsPage`
 - Type-safe GraphQL patterns with codegen
 - `npm run graphql:schema` — download schema from a connected Salesforce org
@@ -54,7 +54,7 @@ The skill references the base app's `npm run graphql:codegen` and `npm run graph
 
 This package includes **rules** that define conventions for GraphQL data access:
 
-- Use `executeGraphQL<T>()` (never raw fetch/axios)
+- Use `getDataSDK()` + `data.graphql?.()` (never raw fetch/axios)
 - Always provide response type generics
 - Use `gql` tag or `.graphql` files (never plain strings)
 - Follow the two-pattern workflow (external file vs. inline)
@@ -74,7 +74,7 @@ cp rules/graphql-data-access-rule.md ~/.clinerules/
 
 The base React app includes reference examples:
 
-- `src/api/graphql.ts` — Core `executeGraphQL()` utility
+- `src/api/graphql.ts` — Core `getDataSDK()` singleton and GraphQL utilities
 - `src/api/utils/accounts.ts` — Pattern 1 (external `.graphql` file + codegen types)
 - `src/api/utils/user.ts` — Pattern 2 (inline `gql` tag)
 - `src/components/AccountsTable.tsx` — Component using GraphQL to fetch and render Accounts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/webapp-template-feature-graphql-experimental",
-  "version": "1.56.0",
+  "version": "1.57.0",
   "description": "GraphQL documentation, agent skills, and rules for Salesforce web applications",
   "license": "SEE LICENSE IN LICENSE.txt",
   "author": "",
@@ -16,5 +16,5 @@
   "scripts": {
     "clean": "echo 'No build artifacts to clean'"
   },
-  "gitHead": "580bc4db5f0190f3b7345056a9f16454455f3652"
+  "gitHead": "79d48250f085dbf33512c356b0ff5fb6acd239d3"
 }

package/rules/graphql-data-access-rule.md

@@ -34,26 +34,25 @@ For a GraphQL operation named `GetHighRevenueAccounts`:
 
 ## Core Types & Function Signatures
 
-### executeGraphQL Function
+### getDataSDK Function
 
-Located in `src/api/graphql.ts`:
+Available from `@salesforce/webapp-experimental/api`:
 
 ```typescript
-function executeGraphQL<T, InputVariables = Record<string, unknown>>(
-  query: string,
-  variables?: InputVariables,
-): Promise<T>;
+import { getDataSDK } from "@salesforce/webapp-experimental/api";
+
+const data = await getDataSDK();
+const response = await data.graphql?.<ResponseType, VariablesType>(query, variables);
 ```
 
-- `T` - The response type (e.g., `GetHighRevenueAccountsQuery`)
-- `InputVariables` - The variables type (e.g., `GetHighRevenueAccountsQueryVariables`)
+`getDataSDK()` returns a lazily-initialized `DataSDK` singleton. The `graphql` method uses optional chaining (`?.`) because not all surfaces support GraphQL.
 
 ### gql Template Tag
 
-Also exported from `graphql.ts` for inline query definitions:
+Also available from `@salesforce/webapp-experimental/api` for inline query definitions:
 
 ```typescript
-import { gql } from "../api/graphql";
+import { gql } from "@salesforce/webapp-experimental/api";
 
 const MY_QUERY = gql`
   query MyQuery {
@@ -68,7 +67,7 @@ The `gql` tag is a template literal that allows defining GraphQL queries inline
 
 ### GraphQLResponse Shape
 
-The raw response wrapper (handled internally by `executeGraphQL`):
+`data.graphql?.()` returns `GraphQLResponse<T>`. Callers destructure `{ data, errors }` and handle errors themselves:
 
 ```typescript
 interface GraphQLResponse<T> {
@@ -81,12 +80,47 @@ interface GraphQLResponse<T> {
 }
 ```
 
+### Handling Mixed Responses (Partial Success)
+
+GraphQL can return **both `data` and `errors`** in the same response (partial success). For example, some fields may resolve while others fail due to field-level security. Choose a strategy per use case:
+
+```typescript
+// Strategy A: Strict — treat any errors as failure (default for most queries)
+if (response?.errors?.length) {
+  throw new Error(response.errors.map((e) => e.message).join("; "));
+}
+const result = response?.data;
+
+// Strategy B: Tolerant — log errors but use partial data
+if (response?.errors?.length) {
+  console.warn("GraphQL partial errors:", response.errors);
+}
+const result = response?.data;
+
+// Strategy C: Discriminated — fail only when no data came back
+if (response?.errors?.length && !response?.data) {
+  throw new Error(response.errors.map((e) => e.message).join("; "));
+}
+if (response?.errors?.length) {
+  console.warn("Partial success with errors:", response.errors);
+}
+const result = response?.data;
+```
+
+**When to use each:**
+
+- **Strategy A** — Default. Use for queries where incomplete data would be misleading (e.g., financial summaries, approval workflows).
+- **Strategy B** — Use when partial data is still useful and the UI can degrade gracefully (e.g., dashboard tiles, optional fields).
+- **Strategy C** — Use for mutations where the operation may succeed but some return fields are inaccessible.
+
+For mutation-specific partial responses, see `docs/generate-mutation-query.md` which covers `PARTIAL` and `FAILED` status handling workflows.
+
 ### NodeOfConnection Utility Type
 
 Extract the node type from a connection (edges/node pattern):
 
 ```typescript
-import { type NodeOfConnection } from "../api/graphql";
+import { type NodeOfConnection } from "@salesforce/webapp-experimental/api";
 
 // Extract Account node type from the query response
 type AccountNode = NodeOfConnection<GetHighRevenueAccountsQuery["uiapi"]["query"]["Account"]>;
@@ -162,22 +196,31 @@ This generates types in `graphql-operations-types.ts`:
 #### Step 3: Import and Use
 
 ```typescript
-import { executeGraphQL, type NodeOfConnection } from "../api/graphql";
+import { getDataSDK, type NodeOfConnection } from "@salesforce/webapp-experimental/api";
 import MY_QUERY from "./query/myQuery.graphql?raw";
 import type { GetMyDataQuery, GetMyDataQueryVariables } from "../graphql-operations-types";
 
-// Extract node type for cleaner return types
 type MyNode = NodeOfConnection<GetMyDataQuery["uiapi"]["query"]["MyObject"]>;
 
 export async function getMyData(variables: GetMyDataQueryVariables): Promise<MyNode[]> {
-  const response = await executeGraphQL<GetMyDataQuery>(MY_QUERY, variables);
-  return response.uiapi?.query?.MyObject?.edges?.map((edge) => edge?.node) || [];
+  const data = await getDataSDK();
+  const response = await data.graphql?.<GetMyDataQuery, GetMyDataQueryVariables>(
+    MY_QUERY,
+    variables,
+  );
+
+  if (response?.errors?.length) {
+    const errorMessages = response.errors.map((e) => e.message).join("; ");
+    throw new Error(`GraphQL Error: ${errorMessages}`);
+  }
+
+  return response?.data?.uiapi?.query?.MyObject?.edges?.map((edge) => edge?.node) || [];
 }
 ```
 
 **Key imports for Pattern 1:**
 
-- `executeGraphQL` - Execute the query
+- `getDataSDK` - Get the DataSDK singleton
 - `NodeOfConnection` - Extract node types from connection responses
 - Query from `.graphql` file with `?raw` suffix
 - Generated types from `graphql-operations-types.ts`
@@ -206,7 +249,7 @@ export async function getMyData(variables: GetMyDataQueryVariables): Promise<MyN
 For simpler queries without variables or when colocation is preferred:
 
 ```typescript
-import { executeGraphQL, gql } from "../api/graphql";
+import { getDataSDK, gql } from "@salesforce/webapp-experimental/api";
 import { type CurrentUserQuery } from "../graphql-operations-types";
 
 const CURRENT_USER_QUERY = gql`
@@ -229,9 +272,14 @@ interface User {
 
 export async function getCurrentUser(): Promise<User | null> {
   try {
-    const response = await executeGraphQL<CurrentUserQuery>(CURRENT_USER_QUERY);
+    const data = await getDataSDK();
+    const response = await data.graphql?.<CurrentUserQuery>(CURRENT_USER_QUERY);
+
+    if (response?.errors?.length) {
+      throw new Error(response.errors.map((e) => e.message).join("; "));
+    }
 
-    const userData = response.uiapi.currentUser;
+    const userData = response?.data?.uiapi.currentUser;
 
     if (!userData) {
       throw new Error("No user data found");
@@ -250,7 +298,7 @@ export async function getCurrentUser(): Promise<User | null> {
 
 **Key imports for Pattern 2:**
 
-- `executeGraphQL` - Execute the query
+- `getDataSDK` - Get the DataSDK singleton
 - `gql` - Template tag for inline query definition
 - Generated types from `graphql-operations-types.ts`
 
@@ -321,18 +369,22 @@ fragment ContactFields on Account {
 ### Usage
 
 ```typescript
-import { executeGraphQL } from "../api/graphql";
+import { getDataSDK } from "@salesforce/webapp-experimental/api";
 import QUERY from "./query/getAccountDetails.graphql?raw";
 import type {
   GetAccountDetailsQuery,
   GetAccountDetailsQueryVariables,
 } from "../graphql-operations-types";
 
-const data = await executeGraphQL<GetAccountDetailsQuery>(QUERY, {
-  id: accountId,
-  includeFinancials: userWantsFinancials,
-  includeContacts: userWantsContacts,
-});
+const data = await getDataSDK();
+const response = await data.graphql?.<GetAccountDetailsQuery, GetAccountDetailsQueryVariables>(
+  QUERY,
+  {
+    id: accountId,
+    includeFinancials: userWantsFinancials,
+    includeContacts: userWantsContacts,
+  },
+);
 ```
 
 ## Anti-Patterns (Not Recommended)
@@ -343,18 +395,21 @@ const data = await executeGraphQL<GetAccountDetailsQuery>(QUERY, {
 // NOT RECOMMENDED: Direct axios/fetch calls for GraphQL
 const response = await axios.post("/graphql", { query });
 
-// PREFERRED: Use executeGraphQL
-const data = await executeGraphQL<ResponseType>(query, variables);
+// PREFERRED: Use the DataSDK
+const data = await getDataSDK();
+const response = await data.graphql?.<ResponseType>(query, variables);
 ```
 
 ### Missing Type Definitions
 
 ```typescript
 // NOT RECOMMENDED: Untyped GraphQL calls
-const data = await executeGraphQL(query);
+const data = await getDataSDK();
+await data.graphql?.(query);
 
 // PREFERRED: Provide response type
-const data = await executeGraphQL<GetMyDataQuery>(query);
+const data = await getDataSDK();
+const response = await data.graphql?.<GetMyDataQuery>(query);
 ```
 
 ### Plain String Queries (Without gql Tag)
@@ -362,23 +417,26 @@ const data = await executeGraphQL<GetMyDataQuery>(query);
 ```typescript
 // NOT RECOMMENDED: Plain string queries without gql tag
 const query = `query { ... }`;
-const data = await executeGraphQL(query);
+const data = await getDataSDK();
+await data.graphql?.(query);
 
 // PREFERRED: Use gql tag for inline queries
 const QUERY = gql`query { ... }`;
-const data = await executeGraphQL<ResponseType>(QUERY);
+const data = await getDataSDK();
+const response = await data.graphql?.<ResponseType>(QUERY);
 
 // OR: Use .graphql file for complex queries
 import QUERY from "./query/myQuery.graphql?raw";
-const data = await executeGraphQL<ResponseType>(QUERY);
+const data = await getDataSDK();
+const response = await data.graphql?.<ResponseType>(QUERY);
 ```
 
-## Benefits of executeGraphQL
+## Benefits of the DataSDK GraphQL API
 
-- Centralized error handling for GraphQL errors
+- Uses the DataSDK with proper authentication and CSRF token handling
 - Consistent typing with `GraphQLResponse<T>` interface
-- Uses the configured `baseDataClient` with proper authentication
-- Automatic extraction of `data` from response envelope
+- Optional chaining (`?.`) safely handles surfaces where GraphQL is unavailable
+- Callers get full `GraphQLResponse<T>` for flexible error handling
 
 ## Quality Checklist
 
@@ -390,18 +448,19 @@ Before completing GraphQL data access code:
 2. [ ] Run `npm run graphql:codegen` to generate types
 3. [ ] Import query with `?raw` suffix
 4. [ ] Import generated types from `graphql-operations-types.ts`
-5. [ ] Use `executeGraphQL<ResponseType>()` with proper generic
-6. [ ] Use `NodeOfConnection` for cleaner node types when needed
-7. [ ] Handle optional chaining for nested response data
-8. [ ] Follow the pattern in `accounts.ts`
+5. [ ] Use `data.graphql?.<ResponseType>()` with proper generic
+6. [ ] Handle `response.errors` and destructure `response.data`
+7. [ ] Use `NodeOfConnection` for cleaner node types when needed
+8. [ ] Handle optional chaining for nested response data
+9. [ ] Follow the pattern in `accounts.ts`
 
 ### For Pattern 2 (inline with gql):
 
 1. [ ] Define query using `gql` template tag
 2. [ ] Ensure query name matches generated types in `graphql-operations-types.ts`
 3. [ ] Import generated types for the query
-4. [ ] Use `executeGraphQL<ResponseType>()` with proper generic
-5. [ ] Handle errors with try/catch when appropriate
+4. [ ] Use `data.graphql?.<ResponseType>()` with proper generic
+5. [ ] Handle `response.errors` and destructure `response.data`
 6. [ ] Handle optional chaining for nested response data
 7. [ ] Follow the pattern in `user.ts`
 

package/skills/graphql-data-access/SKILL.md

@@ -5,7 +5,7 @@ description: Add or modify Salesforce GraphQL data access code. Use when the use
 
 # GraphQL Data Access
 
-Add or modify Salesforce GraphQL data access code using the established `executeGraphQL` utilities and codegen tooling.
+Add or modify Salesforce GraphQL data access code using `getDataSDK()` + `data.graphql?.()` and codegen tooling.
 
 ## When to Use
 
@@ -18,14 +18,14 @@ Add or modify Salesforce GraphQL data access code using the established `execute
 
 The base React app (`base-react-app`) ships with all GraphQL dependencies and tooling pre-configured:
 
-- `@salesforce/sdk-data` — runtime SDK for `executeGraphQL` and `gql`
+- `@salesforce/sdk-data` — runtime SDK for `getDataSDK` and `gql`
 - `@graphql-codegen/cli` + plugins — type generation from `.graphql` files and inline `gql` queries
 - `@graphql-eslint/eslint-plugin` — linting for `.graphql` files and `gql` template literals
 - `graphql` — shared by codegen, ESLint, and schema introspection
 
 Before using this skill, ensure:
 
-1. The `api/graphql.ts` utility exists in the project (provided by the base app)
+1. The `@salesforce/webapp-experimental/api` package is available (provides `getDataSDK`, `gql`, `NodeOfConnection`)
 2. A `schema.graphql` file exists at the project root. If missing, generate it:
    ```bash
    npm run graphql:schema
@@ -96,21 +96,31 @@ This updates `src/api/graphql-operations-types.ts` with:
 
 ```typescript
 // Pattern 1
-import { executeGraphQL, type NodeOfConnection } from "../api/graphql";
+import { getDataSDK, type NodeOfConnection } from "@salesforce/webapp-experimental/api";
 import MY_QUERY from "./query/myQuery.graphql?raw";
 import type { GetMyDataQuery, GetMyDataQueryVariables } from "../graphql-operations-types";
 
 type MyNode = NodeOfConnection<GetMyDataQuery["uiapi"]["query"]["MyObject"]>;
 
 export async function getMyData(variables: GetMyDataQueryVariables): Promise<MyNode[]> {
-  const response = await executeGraphQL<GetMyDataQuery>(MY_QUERY, variables);
-  return response.uiapi?.query?.MyObject?.edges?.map((edge) => edge?.node) || [];
+  const data = await getDataSDK();
+  const response = await data.graphql?.<GetMyDataQuery, GetMyDataQueryVariables>(
+    MY_QUERY,
+    variables,
+  );
+
+  if (response?.errors?.length) {
+    const errorMessages = response.errors.map((e) => e.message).join("; ");
+    throw new Error(`GraphQL Error: ${errorMessages}`);
+  }
+
+  return response?.data?.uiapi?.query?.MyObject?.edges?.map((edge) => edge?.node) || [];
 }
 ```
 
 ```typescript
 // Pattern 2
-import { executeGraphQL, gql } from "../api/graphql";
+import { getDataSDK, gql } from "@salesforce/webapp-experimental/api";
 import type { MySimpleQuery } from "../graphql-operations-types";
 
 const MY_QUERY = gql`
@@ -120,15 +130,16 @@ const MY_QUERY = gql`
 `;
 
 export async function getSimpleData(): Promise<SomeType> {
-  const response = await executeGraphQL<MySimpleQuery>(MY_QUERY);
-  // extract and return data
+  const data = await getDataSDK();
+  const response = await data.graphql?.<MySimpleQuery>(MY_QUERY);
+  // check response.errors, then extract response.data
 }
 ```
 
 ### Step 6: Verify
 
 - [ ] Query field names match the schema exactly (case-sensitive)
-- [ ] Response type generic is provided to `executeGraphQL<T>()`
+- [ ] Response type generic is provided to `data.graphql?.<T>()`
 - [ ] Optional chaining is used for nested response data
 - [ ] Pattern 1: `.graphql` file imported with `?raw` suffix
 - [ ] Pattern 2: Query uses `gql` tag (not plain string)