Make protocol errors available in the error link (#12281)

Co-authored-by: Lenz Weber-Tronic <lorenz.weber-tronic@apollographql.com>

.api-reports/api-report-core.api.md

@@ -259,9 +259,9 @@ export class ApolloLink {
 // @public (undocumented)
 export interface ApolloPayloadResult<TData = Record<string, any>, TExtensions = Record<string, any>> {
     // (undocumented)
-    errors?: ReadonlyArray<Error | string>;
+    errors?: ReadonlyArray<GraphQLFormattedError>;
     // (undocumented)
-    payload: SingleExecutionResult | ExecutionPatchResult | null;
+    payload: SingleExecutionResult<TData, DefaultContext, TExtensions> | ExecutionPatchResult<TData, TExtensions> | null;
 }
 
 // @public (undocumented)

.api-reports/api-report-link_core.api.md

@@ -43,9 +43,11 @@ export class ApolloLink {
 // @public (undocumented)
 export interface ApolloPayloadResult<TData = Record<string, any>, TExtensions = Record<string, any>> {
     // (undocumented)
-    errors?: ReadonlyArray<Error | string>;
+    errors?: ReadonlyArray<GraphQLFormattedError>;
+    // Warning: (ae-forgotten-export) The symbol "DefaultContext" needs to be exported by the entry point index.d.ts
+    //
     // (undocumented)
-    payload: SingleExecutionResult | ExecutionPatchResult | null;
+    payload: SingleExecutionResult<TData, DefaultContext, TExtensions> | ExecutionPatchResult<TData, TExtensions> | null;
 }
 
 // @public (undocumented)
@@ -106,8 +108,6 @@ export const from: typeof ApolloLink.from;
 
 // @public (undocumented)
 export interface GraphQLRequest<TVariables = Record<string, any>> {
-    // Warning: (ae-forgotten-export) The symbol "DefaultContext" needs to be exported by the entry point index.d.ts
-    //
     // (undocumented)
     context?: DefaultContext;
     // (undocumented)

.api-reports/api-report-link_error.api.md

@@ -6,6 +6,7 @@
 
 import type { DocumentNode } from 'graphql';
 import type { FormattedExecutionResult } from 'graphql';
+import type { GraphQLErrorExtensions } from 'graphql';
 import type { GraphQLFormattedError } from 'graphql';
 import { Observable } from 'zen-observable-ts';
 import type { Observer } from 'zen-observable-ts';
@@ -80,14 +81,15 @@ export class ErrorLink extends ApolloLink {
 export interface ErrorResponse {
     // (undocumented)
     forward: NextLink;
-    // (undocumented)
     graphQLErrors?: ReadonlyArray<GraphQLFormattedError>;
     // Warning: (ae-forgotten-export) The symbol "NetworkError" needs to be exported by the entry point index.d.ts
-    //
-    // (undocumented)
     networkError?: NetworkError;
     // (undocumented)
     operation: Operation;
+    protocolErrors?: ReadonlyArray<{
+        message: string;
+        extensions?: GraphQLErrorExtensions[];
+    }>;
     // (undocumented)
     response?: FormattedExecutionResult;
 }

.api-reports/api-report-utilities.api.md

@@ -313,12 +313,12 @@ class ApolloLink {
 // @public (undocumented)
 interface ApolloPayloadResult<TData = Record<string, any>, TExtensions = Record<string, any>> {
     // (undocumented)
-    errors?: ReadonlyArray<Error | string>;
+    errors?: ReadonlyArray<GraphQLFormattedError>;
     // Warning: (ae-forgotten-export) The symbol "SingleExecutionResult" needs to be exported by the entry point index.d.ts
     // Warning: (ae-forgotten-export) The symbol "ExecutionPatchResult" needs to be exported by the entry point index.d.ts
     //
     // (undocumented)
-    payload: SingleExecutionResult | ExecutionPatchResult | null;
+    payload: SingleExecutionResult<TData, DefaultContext, TExtensions> | ExecutionPatchResult<TData, TExtensions> | null;
 }
 
 // @public (undocumented)

.api-reports/api-report.api.md

@@ -282,9 +282,9 @@ export class ApolloLink {
 // @public (undocumented)
 export interface ApolloPayloadResult<TData = Record<string, any>, TExtensions = Record<string, any>> {
     // (undocumented)
-    errors?: ReadonlyArray<Error | string>;
+    errors?: ReadonlyArray<GraphQLFormattedError>;
     // (undocumented)
-    payload: SingleExecutionResult | ExecutionPatchResult | null;
+    payload: SingleExecutionResult<TData, DefaultContext, TExtensions> | ExecutionPatchResult<TData, TExtensions> | null;
 }
 
 // Warning: (ae-forgotten-export) The symbol "ApolloProviderProps" needs to be exported by the entry point index.d.ts

.changeset/giant-peas-lie.md

@@ -0,0 +1,13 @@
+---
+"@apollo/client": patch
+---
+
+Make fatal [tranport-level errors](https://www.apollographql.com/docs/graphos/routing/operations/subscriptions/multipart-protocol#message-and-error-format) from multipart subscriptions available to the error link with the `protocolErrors` property.
+
+```js
+const errorLink = onError(({ protocolErrors }) => {
+  if (protocolErrors) {
+    console.log(protocolErrors);
+  }
+});
+```

.changeset/mighty-shoes-clap.md

@@ -0,0 +1,5 @@
+---
+"@apollo/client": patch
+---
+
+Fix the array type for the `errors` field on the `ApolloPayloadResult` type. This type was always in the shape of the GraphQL error format, per the [multipart subscriptions protocol](https://www.apollographql.com/docs/graphos/routing/operations/subscriptions/multipart-protocol#message-and-error-format) and never a plain string or a JavaScript error object.

docs/source/api/link/apollo-link-error.md

@@ -10,14 +10,23 @@ Use the `onError` link to perform custom logic when a [GraphQL or network error]
 ```js
 import { onError } from "@apollo/client/link/error";
 
-// Log any GraphQL errors or network error that occurred
-const errorLink = onError(({ graphQLErrors, networkError }) => {
+// Log any GraphQL errors, protocol errors, or network error that occurred
+const errorLink = onError(({ graphQLErrors, networkError, protocolErrors }) => {
   if (graphQLErrors)
     graphQLErrors.forEach(({ message, locations, path }) =>
       console.log(
         `[GraphQL error]: Message: ${message}, Location: ${locations}, Path: ${path}`
       )
     );
+
+  if (protocolErrors) {
+    protocolErrors.forEach(({ message, extensions }) => {
+      console.log(
+        `[Protocol error]: Message: ${message}, Extensions: ${JSON.stringify(extensions)}`
+      );
+    });
+  }
+
   if (networkError) console.log(`[Network error]: ${networkError}`);
 });
 ```
@@ -100,6 +109,20 @@ A network error that occurred while attempting to execute the operation, if any.
 </td>
 </tr>
 
+<tr>
+<td>
+
+###### `protocolErrors`
+
+`ReadonlyArray<{ message: string; extensions?: GraphQLErrorExtensions[]; }>`
+</td>
+<td>
+
+Fatal transport-level errors from multipart subscriptions. See the [multipart subscription protocol](https://www.apollographql.com/docs/graphos/routing/operations/subscriptions/multipart-protocol#message-and-error-format) for more information.
+
+</td>
+</tr>
+
 
 <tr>
 <td>

package.json

@@ -165,6 +165,7 @@
     "glob": "8.1.0",
     "globals": "15.14.0",
     "graphql": "16.9.0",
+    "graphql-17-alpha2": "npm:graphql@17.0.0-alpha.2",
     "graphql-ws": "5.16.0",
     "jest": "29.7.0",
     "jest-environment-jsdom": "29.7.0",

src/link/core/types.ts

@@ -50,10 +50,13 @@ export interface ApolloPayloadResult<
   TData = Record<string, any>,
   TExtensions = Record<string, any>,
 > {
-  payload: SingleExecutionResult | ExecutionPatchResult | null;
+  payload:
+    | SingleExecutionResult<TData, DefaultContext, TExtensions>
+    | ExecutionPatchResult<TData, TExtensions>
+    | null;
   // Transport layer errors (as distinct from GraphQL or NetworkErrors),
   // these are fatal errors that will include done: true.
-  errors?: ReadonlyArray<Error | string>;
+  errors?: ReadonlyArray<GraphQLFormattedError>;
 }
 
 export type ExecutionPatchResult<