refactor: expose headers and rawBody instead of Response object

Instead of exposing the full fetch Response (whose body stream is already
consumed), expose the useful data directly on GraphQLResponse:
- headers: Headers - for accessing response headers like Kill-Switch
- rawBody: string - the raw response text for non-GraphQL responses

This avoids the "consumed body stream" footgun while still enabling the
use case from issue #1473 (accessing non-GraphQL error responses).

Author: jasonkuhrt

src/legacy/classes/ClientError.ts

@@ -3,9 +3,8 @@ import type { GraphQLRequestContext, GraphQLResponse } from '../helpers/types.js
 export class ClientError extends Error {
   public response: GraphQLResponse
   public request: GraphQLRequestContext
-  public originalResponse: Response
 
-  constructor(response: GraphQLResponse, request: GraphQLRequestContext, originalResponse: Response) {
+  constructor(response: GraphQLResponse, request: GraphQLRequestContext) {
     const message = `${ClientError.extractMessage(response)}: ${
       JSON.stringify({
         response,
@@ -19,7 +18,6 @@ export class ClientError extends Error {
 
     this.response = response
     this.request = request
-    this.originalResponse = originalResponse
 
     // this is needed as Safari doesn't support .captureStackTrace
     if (typeof Error.captureStackTrace === `function`) {

src/legacy/helpers/runRequest.ts

@@ -71,12 +71,16 @@ export const runRequest = async (input: Input): Promise<ClientError | GraphQLCli
   const fetcher = createFetcher(config.method)
   const fetchResponse = await fetcher(config)
 
+  // Read response body text first (can only be read once)
+  const rawBody = await fetchResponse.text()
+
   // Parse response body FIRST, regardless of HTTP status
   // This allows GraphQL errors to be extracted even when HTTP status is 4xx/5xx (fixes #1281)
   let result
   try {
-    result = await parseResultFromResponse(
-      fetchResponse,
+    result = parseResultFromText(
+      rawBody,
+      fetchResponse.headers.get(CONTENT_TYPE_HEADER),
       input.fetchOptions.jsonSerializer ?? defaultJsonSerializer,
     )
   } catch (error) {
@@ -87,6 +91,7 @@ export const runRequest = async (input: Input): Promise<ClientError | GraphQLCli
   const clientResponseBase = {
     status: fetchResponse.status,
     headers: fetchResponse.headers,
+    rawBody,
   }
 
   // Handle non-2xx HTTP status codes
@@ -100,7 +105,6 @@ export const runRequest = async (input: Input): Promise<ClientError | GraphQLCli
           query: input.request._tag === `Single` ? input.request.document.expression : input.request.query,
           variables: input.request.variables,
         },
-        fetchResponse,
       )
     }
 
@@ -115,7 +119,7 @@ export const runRequest = async (input: Input): Promise<ClientError | GraphQLCli
     return new ClientError(clientResponse, {
       query: input.request._tag === `Single` ? input.request.document.expression : input.request.query,
       variables: input.request.variables,
-    }, fetchResponse)
+    })
   }
 
   // For 2xx responses, parse errors should throw
@@ -133,7 +137,7 @@ export const runRequest = async (input: Input): Promise<ClientError | GraphQLCli
     return new ClientError(clientResponse, {
       query: input.request._tag === `Single` ? input.request.document.expression : input.request.query,
       variables: input.request.variables,
-    }, fetchResponse)
+    })
   }
   switch (result._tag) {
     case `Single`:
@@ -160,9 +164,7 @@ const executionResultClientResponseFields = ($params: Input) => (executionResult
   }
 }
 
-const parseResultFromResponse = async (response: Response, jsonSerializer: JsonSerializer) => {
-  const contentType = response.headers.get(CONTENT_TYPE_HEADER)
-  const text = await response.text()
+const parseResultFromText = (text: string, contentType: string | null, jsonSerializer: JsonSerializer) => {
   if (contentType && isGraphQLContentType(contentType)) {
     return parseGraphQLExecutionResult(jsonSerializer.parse(text))
   } else {

src/legacy/helpers/types.ts

@@ -41,6 +41,11 @@ export interface GraphQLResponse<T = unknown> {
   extensions?: unknown
   status: number
   headers: Headers
+  /**
+   * The raw response body text. Useful for debugging non-GraphQL responses
+   * (e.g., 401/403 errors that return plain JSON instead of GraphQL).
+   */
+  rawBody: string
   [key: string]: unknown
 }
 

tests/legacy/http-status-with-errors.test.ts

@@ -155,4 +155,35 @@ describe(`HTTP 4xx/5xx status codes with GraphQL response body`, () => {
       expect(clientError.response.errors).toEqual(graphqlErrors)
     }
   })
+
+  test(`non-GraphQL response - headers and rawBody should be accessible`, async () => {
+    const nonGraphQLBody = { error: `Kill switch activated`, reason: `maintenance` }
+
+    // Setup mock to return 503 with non-GraphQL response and custom header
+    // eslint-disable-next-line prefer-arrow/prefer-arrow-functions
+    ctx.server.use(`*`, function mock(req, res) {
+      res.status(503)
+        .set(`Kill-Switch`, `true`)
+        .set(`Content-Type`, `application/json`)
+        .send(JSON.stringify(nonGraphQLBody))
+    })
+
+    const client = new GraphQLClient(ctx.url)
+
+    try {
+      await client.request(`{ user { id } }`)
+      expect.fail(`Expected ClientError to be thrown`)
+    } catch (error) {
+      expect(error).toBeInstanceOf(ClientError)
+      const clientError = error as ClientError
+      expect(clientError.response.status).toBe(503)
+      // Verify headers are accessible
+      expect(clientError.response.headers).toBeInstanceOf(Headers)
+      expect(clientError.response.headers.get(`Kill-Switch`)).toBe(`true`)
+      // Verify rawBody is accessible for non-GraphQL responses
+      expect(clientError.response.rawBody).toBe(JSON.stringify(nonGraphQLBody))
+      // Can parse the raw body to get detailed error info
+      expect(JSON.parse(clientError.response.rawBody)).toEqual(nonGraphQLBody)
+    }
+  })
 })