Core Client Operations

/**
 * Main Linear API client that extends LinearSdk with authentication and error handling
 */
class LinearClient extends LinearSdk {
  /**
   * Creates a Linear API client
   * @param options - Client configuration options including authentication
   */
  constructor(options: LinearClientOptions);

  /** Parsed client configuration options */
  options: LinearClientParsedOptions;
  /** Underlying GraphQL client for low-level operations */
  client: LinearGraphQLClient;
}

interface LinearClientOptions extends RequestInit {
  /** Personal API token generated from https://linear.app/settings/account/security */
  apiKey?: string;
  /** The access token returned from OAuth endpoints */
  accessToken?: string;
  /** The URL to the Linear GraphQL API (defaults to production) */
  apiUrl?: string;
}

interface LinearClientParsedOptions extends RequestInit {
  /** The URL to the Linear GraphQL API defaulted to production */
  apiUrl: string;
}

import { LinearClient } from "@linear/sdk";

// Using API key authentication
const client = new LinearClient({
  apiKey: "lin_api_your_api_key_here"
});

// Using OAuth access token
const client = new LinearClient({
  accessToken: "Bearer your_oauth_token_here"
});

// Custom API URL and additional options
const client = new LinearClient({
  apiKey: "lin_api_your_api_key_here",
  apiUrl: "https://api.linear.app/graphql",
  headers: {
    "Custom-Header": "value"
  }
});

/**
 * Create an isomorphic GraphQL client for Linear API requests
 */
class LinearGraphQLClient {
  /**
   * Creates a GraphQL client
   * @param url - Base URL to send requests to
   * @param options - Request options and headers
   */
  constructor(url: string, options?: RequestInit);

  /**
   * Execute a GraphQL request and return the data
   * @param document - GraphQL document node or query string
   * @param variables - Variables to pass to the query
   * @param requestHeaders - Additional headers for this request
   * @returns Promise resolving to the response data
   */
  request<Data, Variables extends Record<string, unknown>>(
    document: DocumentNode | string,
    variables?: Variables,
    requestHeaders?: RequestInit["headers"]
  ): Promise<Data>;

  /**
   * Execute a raw GraphQL request and return the full response
   * @param query - GraphQL query string
   * @param variables - Variables to pass to the query
   * @param requestHeaders - Additional headers for this request
   * @returns Promise resolving to the raw response
   */
  rawRequest<Data, Variables extends Record<string, unknown>>(
    query: string,
    variables?: Variables,
    requestHeaders?: RequestInit["headers"]
  ): Promise<LinearRawResponse<Data>>;

  /**
   * Set a single request header
   * @param key - Header name
   * @param value - Header value
   * @returns This client instance for chaining
   */
  setHeader(key: string, value: string): LinearGraphQLClient;

  /**
   * Set multiple request headers
   * @param headers - Headers object
   * @returns This client instance for chaining
   */
  setHeaders(headers: RequestInit["headers"]): LinearGraphQLClient;
}

import { LinearGraphQLClient } from "@linear/sdk";

// Create a GraphQL client
const graphqlClient = new LinearGraphQLClient("https://api.linear.app/graphql", {
  headers: {
    Authorization: "lin_api_your_api_key_here"
  }
});

// Execute a query
const data = await graphqlClient.request(`
  query GetIssues($first: Int) {
    issues(first: $first) {
      nodes {
        id
        title
        state {
          name
        }
      }
    }
  }
`, { first: 10 });

// Get raw response with metadata
const rawResponse = await graphqlClient.rawRequest(`
  query { viewer { id name email } }
`);

console.log(rawResponse.status); // HTTP status
console.log(rawResponse.headers); // Response headers
console.log(rawResponse.data); // GraphQL data

/**
 * Base class to provide a request function and utilities
 */
class Request {
  /**
   * Creates a new request instance
   * @param request - Function to call the GraphQL client
   */
  constructor(request: LinearRequest);

  /**
   * Helper to paginate over all pages of a given connection query
   * @param fn - The query function to paginate
   * @param args - The arguments to pass to the query
   * @returns Promise resolving to all nodes across pages
   */
  async paginate<T extends Node, U>(
    fn: (variables: U) => LinearFetch<Connection<T>>,
    args: U
  ): Promise<T[]>;
}

/**
 * Error class for GraphQL client request failures
 */
class GraphQLClientError<Data, Variables extends Record<string, unknown>> extends Error {
  /** Raw response from the Linear API */
  response: LinearRawResponse<Data>;
  /** Request context that caused the error */
  request: GraphQLRequestContext<Variables>;

  /**
   * Creates a GraphQL client error
   * @param response - The raw response from the Linear API
   * @param request - Information about the request resulting in the error
   */
  constructor(response: LinearRawResponse<Data>, request: GraphQLRequestContext<Variables>);
}

/** Function type for making GraphQL requests */
type LinearRequest = <Response, Variables extends Record<string, unknown>>(
  doc: DocumentNode,
  variables?: Variables
) => Promise<Response>;

/** Promise wrapper for Linear API responses */
type LinearFetch<Response> = Promise<Response>;

/** Raw response from the Linear GraphQL API */
interface LinearRawResponse<Data> {
  /** The returned data */
  data?: Data;
  /** Any extensions returned by the Linear API */
  extensions?: unknown;
  /** Response headers */
  headers?: Headers;
  /** Response status */
  status?: number;
  /** An error message */
  error?: string;
  /** Any GraphQL errors returned by the Linear API */
  errors?: LinearGraphQLErrorRaw[];
}

/** Description of a GraphQL request used in error handling */
interface GraphQLRequestContext<Variables extends Record<string, unknown>> {
  query: string;
  variables?: Variables;
}