graphqlClient.ts

import type { Client, IntegrationFn } from '@sentry/core';
import {
 defineIntegration,
 hasSpanStreamingEnabled,
 isObjectLike,
 isString,
 SEMANTIC_ATTRIBUTE_HTTP_REQUEST_METHOD,
 spanToJSON,
 stringMatchesSomePattern,
} from '@sentry/core';
import type { FetchHint, XhrHint } from '@sentry/browser-utils';
import { getBodyString, getFetchRequestArgBody, SENTRY_XHR_DATA_KEY } from '@sentry/browser-utils';
import {
 GRAPHQL_DOCUMENT,
 GRAPHQL_OPERATION_NAME,
 GRAPHQL_OPERATION_TYPE,
 HTTP_METHOD,
 SENTRY_OP,
 URL_FULL,
} from '@sentry/conventions/attributes';

interface GraphQLClientOptions {
 endpoints: Array<string | RegExp>;
}

/** Standard graphql request shape: https://graphql.org/learn/serving-over-http/#post-request-and-body */
interface GraphQLStandardRequest {
 query: string;
 operationName?: string;
 variables?: Record<string, unknown>;
 extensions?: Record<string, unknown>;
}

/** Persisted operation request */
interface GraphQLPersistedRequest {
 operationName: string;
 variables?: Record<string, unknown>;
 extensions: {
 persistedQuery: {
 version: number;
 sha256Hash: string;
 };
 } & Record<string, unknown>;
}

type GraphQLRequestPayload = GraphQLStandardRequest | GraphQLPersistedRequest;

interface GraphQLOperation {
 operationType?: string;
 operationName?: string;
}

const INTEGRATION_NAME = 'GraphQLClient' as const;

const _graphqlClientIntegration = ((options: GraphQLClientOptions) => {
 return {
 name: INTEGRATION_NAME,
 setup(client: Client) {
 _updateSpanWithGraphQLData(client, options);
 _updateBreadcrumbWithGraphQLData(client, options);
 },
 };
}) satisfies IntegrationFn;

function _updateSpanWithGraphQLData(client: Client, options: GraphQLClientOptions): void {
 client.on('beforeOutgoingRequestSpan', (span, hint) => {
 const spanJSON = spanToJSON(span);

 const spanAttributes = spanJSON.attributes;
 const spanOp = spanAttributes[SENTRY_OP];

 const isHttpClientSpan = spanOp === 'http.client';

 if (!isHttpClientSpan) {
 return;
 }

 const httpUrl = spanAttributes[URL_FULL];
 // oxlint-disable-next-line typescript/no-deprecated
 const httpMethod = spanAttributes[SEMANTIC_ATTRIBUTE_HTTP_REQUEST_METHOD] || spanAttributes[HTTP_METHOD];

 if (!isString(httpUrl) || !isString(httpMethod)) {
 return;
 }

 const { endpoints } = options;
 const isTracedGraphqlEndpoint = stringMatchesSomePattern(httpUrl, endpoints);
 const payload = getRequestPayloadXhrOrFetch(hint as XhrHint | FetchHint);

 if (isTracedGraphqlEndpoint && payload) {
 const graphqlBody = getGraphQLRequestPayload(payload);

 if (graphqlBody) {
 // With span streaming the span already carries a low-cardinality name, so it must not be
 // renamed back to one containing the URL. The operation stays reachable as an attribute.
 if (!hasSpanStreamingEnabled(client)) {
 span.updateName(`${httpMethod} ${httpUrl} (${_getGraphQLOperation(graphqlBody)})`);
 }

 const { operationName, operationType } = _getGraphQLOperationDetails(graphqlBody);
 span.setAttribute(GRAPHQL_OPERATION_NAME, operationName);
 span.setAttribute(GRAPHQL_OPERATION_TYPE, operationType);

 // Handle standard requests - capture the query document when enabled via dataCollection (default true)
 if (isStandardRequest(graphqlBody) && client.getDataCollectionOptions().graphQL.document === true) {
 span.setAttribute(GRAPHQL_DOCUMENT, graphqlBody.query);
 }

 // Handle persisted operations - capture hash for debugging
 if (isPersistedRequest(graphqlBody)) {
 span.setAttribute('graphql.persisted_query.hash.sha256', graphqlBody.extensions.persistedQuery.sha256Hash);
 span.setAttribute('graphql.persisted_query.version', graphqlBody.extensions.persistedQuery.version);
 }
 }
 }
 });
}

function _updateBreadcrumbWithGraphQLData(client: Client, options: GraphQLClientOptions): void {
 client.on('beforeOutgoingRequestBreadcrumb', (breadcrumb, handlerData) => {
 const { category, type, data } = breadcrumb;

 const isFetch = category === 'fetch';
 const isXhr = category === 'xhr';
 const isHttpBreadcrumb = type === 'http';

 if (isHttpBreadcrumb && (isFetch || isXhr)) {
 const httpUrl = data?.url;
 const { endpoints } = options;

 const isTracedGraphqlEndpoint = stringMatchesSomePattern(httpUrl, endpoints);
 const payload = getRequestPayloadXhrOrFetch(handlerData as XhrHint | FetchHint);

 if (isTracedGraphqlEndpoint && data && payload) {
 const graphqlBody = getGraphQLRequestPayload(payload);

 if (!data.graphql && graphqlBody) {
 const operationInfo = _getGraphQLOperation(graphqlBody);

 data['graphql.operation'] = operationInfo;

 if (isStandardRequest(graphqlBody) && client.getDataCollectionOptions().graphQL.document === true) {
 data[GRAPHQL_DOCUMENT] = graphqlBody.query;
 }

 if (isPersistedRequest(graphqlBody)) {
 data['graphql.persisted_query.hash.sha256'] = graphqlBody.extensions.persistedQuery.sha256Hash;
 data['graphql.persisted_query.version'] = graphqlBody.extensions.persistedQuery.version;
 }
 }
 }
 }
 });
}

/**
 * The operation name and type of a GraphQL request. Persisted operations carry no query document, so
 * their type is unknown.
 */
function _getGraphQLOperationDetails(requestBody: GraphQLRequestPayload): GraphQLOperation {
 if (isPersistedRequest(requestBody)) {
 return { operationName: requestBody.operationName, operationType: undefined };
 }

 if (isStandardRequest(requestBody)) {
 const { query: graphqlQuery, operationName: graphqlOperationName } = requestBody;
 const { operationName = graphqlOperationName, operationType } = parseGraphQLQuery(graphqlQuery);
 return { operationName, operationType };
 }

 return { operationName: undefined, operationType: undefined };
}

/**
 * @param requestBody - GraphQL request
 * @returns A formatted version of the request: 'TYPE NAME' or 'TYPE' or 'persisted NAME'
 */
export function _getGraphQLOperation(requestBody: GraphQLRequestPayload): string {
 // Handle persisted operations
 if (isPersistedRequest(requestBody)) {
 return `persisted ${requestBody.operationName}`;
 }

 // Handle standard GraphQL requests
 if (isStandardRequest(requestBody)) {
 const { operationName, operationType } = _getGraphQLOperationDetails(requestBody);
 return operationName ? `${operationType} ${operationName}` : `${operationType}`;
 }

 // Fallback for unknown request types
 return 'unknown';
}

/**
 * Get the request body/payload based on the shape of the hint.
 *
 * Exported for tests only.
 */
export function getRequestPayloadXhrOrFetch(hint: XhrHint | FetchHint): string | undefined {
 const isXhr = 'xhr' in hint;

 let body: string | undefined;

 if (isXhr) {
 const sentryXhrData = hint.xhr[SENTRY_XHR_DATA_KEY];
 body = sentryXhrData && getBodyString(sentryXhrData.body)[0];
 } else {
 const sentryFetchData = getFetchRequestArgBody(hint.input);
 body = getBodyString(sentryFetchData)[0];
 }

 return body;
}

/**
 * Extract the name and type of the operation from the GraphQL query.
 *
 * Exported for tests only.
 */
export function parseGraphQLQuery(query: string): GraphQLOperation {
 const namedQueryRe = /^(?:\s*)(query|mutation|subscription)(?:\s*)(\w+)(?:\s*)[{(]/;
 const unnamedQueryRe = /^(?:\s*)(query|mutation|subscription)(?:\s*)[{(]/;

 const namedMatch = query.match(namedQueryRe);
 if (namedMatch) {
 return {
 operationType: namedMatch[1],
 operationName: namedMatch[2],
 };
 }

 const unnamedMatch = query.match(unnamedQueryRe);
 if (unnamedMatch) {
 return {
 operationType: unnamedMatch[1],
 operationName: undefined,
 };
 }
 return {
 operationType: undefined,
 operationName: undefined,
 };
}

/**
 * Helper to safely check if a value is a non-null object
 */

/**
 * Type guard to check if a request is a standard GraphQL request
 */
function isStandardRequest(payload: unknown): payload is GraphQLStandardRequest {
 return isObjectLike(payload) && typeof payload.query === 'string';
}

/**
 * Type guard to check if a request is a persisted operation request
 */
function isPersistedRequest(payload: unknown): payload is GraphQLPersistedRequest {
 return (
 isObjectLike(payload) &&
 typeof payload.operationName === 'string' &&
 isObjectLike(payload.extensions) &&
 isObjectLike(payload.extensions.persistedQuery) &&
 typeof payload.extensions.persistedQuery.sha256Hash === 'string' &&
 typeof payload.extensions.persistedQuery.version === 'number'
 );
}

/**
 * Extract the payload of a request if it's GraphQL.
 * Exported for tests only.
 * @param payload - A valid JSON string
 * @returns A POJO or undefined
 */
export function getGraphQLRequestPayload(payload: string): GraphQLRequestPayload | undefined {
 try {
 const requestBody = JSON.parse(payload);

 // Return any valid GraphQL request (standard, persisted, or APQ retry with both)
 if (isStandardRequest(requestBody) || isPersistedRequest(requestBody)) {
 return requestBody;
 }

 // Not a GraphQL request
 return undefined;
 } catch {
 // Invalid JSON
 return undefined;
 }
}

/**
 * This integration ensures that GraphQL requests made in the browser
 * have their GraphQL-specific data captured and attached to spans and breadcrumbs.
 */
export const graphqlClientIntegration = defineIntegration(_graphqlClientIntegration);