/**
 * GraphQL client types.
 */

import type { z } from "zod";

import type { BaseIntegrationClient } from "../../types.js";
import type { TraceMetadata } from "../registry.js";

/**
 * GraphQL client for executing queries and mutations.
 *
 * Provides methods for executing GraphQL operations against configured
 * GraphQL endpoints with required Zod schema validation.
 *
 * @example
 * ```typescript
 * // Declare in api(): integrations: { graphql: graphql(INTEGRATION_ID) }
 * // In run(), access via ctx.integrations.graphql
 *
 * // Execute a query
 * // Schema validates the full GraphQL response (including data wrapper)
 * const ResponseSchema = z.object({
 *   data: z.object({
 *     user: z.object({
 *       id: z.string(),
 *       name: z.string(),
 *       email: z.string(),
 *     }),
 *   }),
 * });
 *
 * const result = await graphql.query(
 *   `query GetUser($id: ID!) {
 *     user(id: $id) {
 *       id
 *       name
 *       email
 *     }
 *   }`,
 *   { response: ResponseSchema },
 *   { id: '123' }
 * );
 * // Access data explicitly
 * console.log(result.data.user.name);
 *
 * // Execute a mutation
 * const MutationResponseSchema = z.object({
 *   data: z.object({
 *     createUser: z.object({
 *       id: z.string(),
 *     }),
 *   }),
 * });
 *
 * await graphql.mutation(
 *   `mutation CreateUser($name: String!) {
 *     createUser(name: $name) {
 *       id
 *     }
 *   }`,
 *   { response: MutationResponseSchema },
 *   { name: 'John Doe' }
 * );
 *
 * // Send per-request headers (e.g. a dynamic Authorization token).
 * // Static headers and auth configured on the integration apply automatically;
 * // use this parameter only for values that vary per request.
 * await graphql.query(
 *   `query { me { id } }`,
 *   { response: z.object({ data: z.object({ me: z.object({ id: z.string() }) }) }) },
 *   undefined,
 *   undefined,
 *   { Authorization: `Bearer ${token}` },
 * );
 * ```
 */
export interface GraphQLClient extends BaseIntegrationClient {
  /**
   * Execute a GraphQL query.
   *
   * @param query - GraphQL query string
   * @param schema - Zod schema for response validation (REQUIRED)
   * @param variables - Optional variables for the query. **Note:** since both `variables` and
   *   `metadata` accept plain objects, pass `undefined` for variables when you only need metadata:
   *   `query(q, schema, undefined, { label: "..." })`
   * @param metadata - Optional trace metadata for observability
   * @param headers - Optional HTTP headers to include on this request. Static
   *   headers and auth configured on the integration apply automatically; use
   *   this parameter only for values that vary per request (e.g. a bearer token
   *   derived from the API's input).
   * @returns Validated query result
   *
   * @example
   * ```typescript
   * // Schema validates full GraphQL response (including data wrapper)
   * const result = await graphql.query(
   *   'query { users { id name } }',
   *   { response: z.object({
   *     data: z.object({
   *       users: z.array(z.object({ id: z.string(), name: z.string() }))
   *     })
   *   }) }
   * );
   * // result.data.users is typed as Array<{ id: string; name: string }>
   * ```
   */
  query<TResponse>(
    query: string,
    schema: { response: z.ZodSchema<TResponse> },
    variables?: Record<string, unknown>,
    metadata?: TraceMetadata,
    headers?: Record<string, string>,
  ): Promise<TResponse>;

  /**
   * Execute a GraphQL mutation.
   *
   * @param mutation - GraphQL mutation string
   * @param schema - Zod schema for response validation (REQUIRED)
   * @param variables - Optional variables for the mutation. **Note:** since both `variables` and
   *   `metadata` accept plain objects, pass `undefined` for variables when you only need metadata:
   *   `mutation(m, schema, undefined, { label: "..." })`
   * @param metadata - Optional trace metadata for observability
   * @param headers - Optional HTTP headers to include on this request. Static
   *   headers and auth configured on the integration apply automatically; use
   *   this parameter only for values that vary per request (e.g. a bearer token
   *   derived from the API's input).
   * @returns Validated mutation result
   *
   * @example
   * ```typescript
   * // Schema validates full GraphQL response (including data wrapper)
   * const result = await graphql.mutation(
   *   'mutation CreateUser($name: String!) { createUser(name: $name) { id } }',
   *   { response: z.object({
   *     data: z.object({
   *       createUser: z.object({ id: z.string() })
   *     })
   *   }) },
   *   { name: 'John' }
   * );
   * // result.data.createUser is typed as { id: string }
   * ```
   */
  mutation<TResponse>(
    mutation: string,
    schema: { response: z.ZodSchema<TResponse> },
    variables?: Record<string, unknown>,
    metadata?: TraceMetadata,
    headers?: Record<string, string>,
  ): Promise<TResponse>;
}