Add Logging for GraphQL Deprecated Reason

* Add log and log type for deprecation reason/notice
* Add documentation covering the new log type
* Allow the logging of any deprecation reason from GraphQL requests to allow apps to monitor these

Author: jordanfinners

.changeset/dirty-pumas-laugh.md

@@ -0,0 +1,7 @@
+---
+'@shopify/admin-api-client': minor
+'@shopify/graphql-client': minor
+'@shopify/shopify-api': minor
+---
+
+Add Logging for GraphQL Deprecated Reason

packages/api-clients/admin-api-client/README.md

@@ -58,7 +58,7 @@ const {data, errors, extensions} = await client.request(operation, {
 | userAgentPrefix? | `string`                                                                                                                                                      | Any prefix you wish to include in the User-Agent for requests made by the library.                                                                                                                            |
 | retries?         | `number`                                                                                                                                                      | The number of HTTP request retries if the request was abandoned or the server responded with a `Too Many Requests (429)` or `Service Unavailable (503)` response. Default value is `0`. Maximum value is `3`. |
 | customFetchApi?  | `(url: string, init?: {method?: string, headers?: HeaderInit, body?: string}) => Promise<Response>`                                                           | A replacement `fetch` function that will be used in all client network requests. By default, the client uses `window.fetch()`.                                                                                |
-| logger?          | `(logContent:`[`UnsupportedApiVersionLog`](#unsupportedapiversionlog) `\|`[`HTTPResponseLog`](#httpresponselog)`\|`[`HTTPRetryLog`](#httpretrylog)`) => void` | A logger function that accepts [log content objects](#log-content-types). This logger will be called in certain conditions with contextual information.                                                       |
+| logger?          | `(logContent:`[`UnsupportedApiVersionLog`](#unsupportedapiversionlog) `\|`[`HTTPResponseLog`](#httpresponselog)`\|`[`HTTPRetryLog`](#httpretrylog)`\|`[`HTTPResponseGraphQLDeprecationNotice`](#httpresponsegraphqldeprecationnotice)`) => void` | A logger function that accepts [log content objects](#log-content-types). This logger will be called in certain conditions with contextual information.                                                       |
 
 ### Client properties
 
@@ -363,6 +363,15 @@ This log content is sent to the logger whenever the client attempts to retry HTT
 | type     | `LogType['HTTP-Retry']`                                                                                                  | The type of log content. Is always set to `HTTP-Retry`                                                                                                                                                                                                                           |
 | content  | `{`[`requestParams`](#requestparams)`: [url, init?], lastResponse?: Response, retryAttempt: number, maxRetries: number}` | Contextual data regarding the upcoming retry attempt. <br /><br/>`requestParams`: [parameters](#requestparams) used in the request<br/>`lastResponse`: previous response <br/> `retryAttempt`: the current retry attempt count <br/> `maxRetries`: the maximum number of retries |
 
+### `HTTPResponseGraphQLDeprecationNotice`
+
+This log content is sent to the logger whenever a HTTP response with a `X-Shopify-API-Deprecated-Reason` is received by the client.
+
+| Property | Type                     | Description                        |
+| -------- | ------------------------ | ---------------------------------- |
+| type      | `LogType['HTTP-Response-GraphQL-Deprecation-Notice']`                 | The type of log content. Is always set to `HTTP-Response-GraphQL-Deprecation-Notice`            |
+| content  | `{`[`requestParams`](#requestparams)`: [url, init?], deprecationNotice: string}` | Contextual data regarding the request and received deprecation information |
+
 #### `RequestParams`
 
 | Property | Type                                                     | Description             |

packages/api-clients/admin-api-client/src/index.ts

@@ -16,6 +16,7 @@ export type {
   FetchResponseBody,
   HTTPResponseLog,
   HTTPRetryLog,
+  HTTPResponseGraphQLDeprecationNotice,
   LogContent,
   ResponseWithType,
   ReturnData,

packages/api-clients/graphql-client/README.md

@@ -71,7 +71,7 @@ const client = createGraphQLClient({
 | headers  | `Record<string, string \| string[]>` | Headers to be included in requests |
 | retries?  | `number` | The number of HTTP request retries if the request was abandoned or the server responded with a `Too Many Requests (429)` or `Service Unavailable (503)` response. Default value is `0`. Maximum value is `3`. |
 | customFetchApi?  | `(url: string, init?: {method?: string, headers?: HeaderInit, body?: string}) => Promise<Response>` | A replacement `fetch` function that will be used in all client network requests. By default, the client uses `window.fetch()`. |
-| logger?  | `(logContent: `[`HTTPResponseLog`](#httpresponselog)`\|`[`HTTPRetryLog`](#httpretrylog)`) => void` | A logger function that accepts [log content objects](#log-content-types). This logger will be called in certain conditions with contextual information.  |
+| logger?  | `(logContent: `[`HTTPResponseLog`](#httpresponselog)`\|`[`HTTPRetryLog`](#httpretrylog)`\|`[`HTTPResponseGraphQLDeprecationNotice`](#httpresponsegraphqldeprecationnotice)`) => void` | A logger function that accepts [log content objects](#log-content-types). This logger will be called in certain conditions with contextual information.  |
 
 ## Client properties
 
@@ -313,6 +313,15 @@ This log content is sent to the logger whenever the client attempts to retry HTT
 | type      | `LogType['HTTP-Retry']`                 | The type of log content. Is always set to `HTTP-Retry`            |
 | content  | `{`[`requestParams`](#requestparams)`: [url, init?], lastResponse?: Response, retryAttempt: number, maxRetries: number}` | Contextual data regarding the upcoming retry attempt. <br /><br/>`requestParams`: [parameters](#requestparams) used in the request<br/>`lastResponse`: previous response <br/> `retryAttempt`: the current retry attempt count <br/> `maxRetries`: the maximum number of retries  |
 
+### `HTTPResponseGraphQLDeprecationNotice`
+
+This log content is sent to the logger whenever a HTTP response with a `X-Shopify-API-Deprecated-Reason` is received by the client.
+
+| Property | Type                     | Description                        |
+| -------- | ------------------------ | ---------------------------------- |
+| type      | `LogType['HTTP-Response-GraphQL-Deprecation-Notice']`                 | The type of log content. Is always set to `HTTP-Response-GraphQL-Deprecation-Notice`            |
+| content  | `{`[`requestParams`](#requestparams)`: [url, init?], deprecationNotice: string}` | Contextual data regarding the request and received deprecation information |
+
 ### `RequestParams`
 
 | Property | Type                     | Description                        |

packages/api-clients/graphql-client/src/graphql-client/http-fetch.ts

@@ -1,6 +1,6 @@
-import {CLIENT, RETRIABLE_STATUS_CODES, RETRY_WAIT_TIME} from './constants';
-import {CustomFetchApi, GraphQLClient, Logger} from './types';
-import {formatErrorMessage, getErrorMessage} from './utilities';
+import { CLIENT, RETRIABLE_STATUS_CODES, RETRY_WAIT_TIME } from './constants';
+import { CustomFetchApi, GraphQLClient, Logger } from './types';
+import { formatErrorMessage, getErrorMessage } from './utilities';
 
 interface GenerateHttpFetchOptions {
   clientLogger: Logger;
@@ -45,6 +45,17 @@ export function generateHttpFetch({
         throw new Error();
       }
 
+      const deprecationNotice = response?.headers.get('X-Shopify-API-Deprecated-Reason') || '';
+      if (deprecationNotice) {
+        clientLogger({
+          type: 'HTTP-Response-GraphQL-Deprecation-Notice',
+          content: {
+            requestParams,
+            deprecationNotice,
+          },
+        });
+      }
+
       return response;
     } catch (error) {
       if (nextCount <= maxTries) {
@@ -68,10 +79,9 @@ export function generateHttpFetch({
 
       throw new Error(
         formatErrorMessage(
-          `${
-            maxRetries > 0
-              ? `Attempted maximum number of ${maxRetries} network retries. Last message - `
-              : ''
+          `${maxRetries > 0
+            ? `Attempted maximum number of ${maxRetries} network retries. Last message - `
+            : ''
           }${getErrorMessage(error)}`,
           client,
         ),

packages/api-clients/graphql-client/src/graphql-client/tests/http-fetch.test.ts

@@ -116,6 +116,43 @@ describe('httpFetch utility', () => {
         expect(fetch).toHaveBeenCalledTimes(1);
       });
 
+      it('logs any graphql deprecation notices', async () => {
+        const httpFetch = generateHttpFetch({clientLogger});
+        const mockedResponseWithDeprecation = new Response(
+          JSON.stringify({data: {}}),
+          {
+            status: 200,
+            headers: new Headers({
+              'X-Shopify-API-Deprecated-Reason': 'A deprecation notice',
+              'Content-Type': 'application/json',
+            }),
+          },
+        );
+
+        fetchMock.mockResolvedValue(mockedResponseWithDeprecation);
+
+        const requestParams: Parameters<CustomFetchApi> = [
+          url,
+          {
+            method: 'POST',
+            body: JSON.stringify({query: operation}),
+          },
+        ];
+        const response = await httpFetch(requestParams, 1, 2);
+
+        expect(response.status).toBe(200);
+        expect(fetch).toHaveBeenCalledTimes(1);
+
+        expect(clientLogger).toHaveBeenCalledTimes(1);
+        expect(clientLogger).toHaveBeenNthCalledWith(1, {
+          type: 'HTTP-Response-GraphQL-Deprecation-Notice',
+          content: {
+            requestParams,
+            deprecationNotice: 'A deprecation notice',
+          },
+        });
+      });
+
       describe('retries', () => {
         let httpFetch: ReturnType<typeof generateHttpFetch>;
 

packages/api-clients/graphql-client/src/graphql-client/types.ts

@@ -60,6 +60,14 @@ export interface HTTPResponseLog extends LogContent {
   };
 }
 
+export interface HTTPResponseGraphQLDeprecationNotice extends LogContent {
+  type: 'HTTP-Response-GraphQL-Deprecation-Notice';
+  content: {
+    requestParams: Parameters<CustomFetchApi>;
+    deprecationNotice: string;
+  };
+}
+
 export interface HTTPRetryLog extends LogContent {
   type: 'HTTP-Retry';
   content: {
@@ -70,7 +78,7 @@ export interface HTTPRetryLog extends LogContent {
   };
 }
 
-export type LogContentTypes = HTTPResponseLog | HTTPRetryLog;
+export type LogContentTypes = HTTPResponseLog | HTTPRetryLog | HTTPResponseGraphQLDeprecationNotice;
 
 export type Logger<TLogContentTypes = LogContentTypes> = (
   logContent: TLogContentTypes,

packages/apps/shopify-api/lib/clients/common.ts

@@ -1,6 +1,7 @@
 import {
   HTTPResponseLog,
   HTTPRetryLog,
+  HTTPResponseGraphQLDeprecationNotice,
   LogContent,
 } from '@shopify/admin-api-client';
 import {StatusCode} from '@shopify/network';
@@ -47,6 +48,14 @@ export function clientLoggerFactory(config: ConfigInterface) {
           });
           break;
         }
+        case 'HTTP-Response-GraphQL-Deprecation-Notice': {
+          const responseLog: HTTPResponseGraphQLDeprecationNotice['content'] = logContent.content;
+          logger(config).debug('Received response containing Deprecated GraphQL Notice', {
+            requestParams: JSON.stringify(responseLog.requestParams),
+            deprecationNotice: responseLog.deprecationNotice,
+          });
+          break;
+        }
         default: {
           logger(config).debug(`HTTP request event: ${logContent.content}`);
           break;