Generic GraphQL access. This is the whole GraphQL API: any query or mutation, including the corners REST cannot reach, such as Projects v2 and Discussions.

query/3 runs a single operation. stream/4 walks a cursor-paginated connection into a lazy Stream, mirroring GhEx.REST.stream/3 so both transports paginate through one mental model.

Result shape

query/3 returns {:ok, data, meta} on success, where data is the contents of the GraphQL data field and meta is a GhEx.GraphQL.Meta. GraphQL answers with HTTP 200 even on failure, so a response carrying a non-empty errors array becomes {:error, %GhEx.Error{}}; any partial data is preserved on the error's :body. Transport failures return the Req exception.

Variables

Pass variables as a keyword list or map. Keys may be atoms or strings; both serialize to the matching $name in the query.

GhEx.GraphQL.query(client, ~s|query($login: String!) {
  user(login: $login) { name }
}|, login: "joshrotenberg")

Pagination

stream/4 drives a connection's pageInfo. The query must accept a cursor variable (named cursor by default) wired into the connection's after: argument, and must select pageInfo { hasNextPage endCursor } alongside the nodes. Tell stream/4 where the connection lives with :path:

query = ~s|query($org: String!, $cursor: String) {
  organization(login: $org) {
    projectsV2(first: 100, after: $cursor) {
      nodes { id title }
      pageInfo { hasNextPage endCursor }
    }
  }
}|

client
|> GhEx.GraphQL.stream(query, [org: "joshrotenberg"], path: ["organization", "projectsV2"])
|> Stream.map(& &1["title"])
|> Enum.to_list()

A failed page raises GhEx.Error.