ExShopifyApp.Graphql (ex_shopify_app v1.2.0)

A minimal Shopify Admin GraphQL client, plus GID helpers.

The client is authenticated with a shop's shopify_domain and offline access_token (an ExShopifyApp.Shop.authorized/0 reference). The ExShopifyApp.AccessToken.Token struct already carries both fields, so it can be passed directly; any map/struct exposing :shopify_domain and :access_token works too.

Docs: https://shopify.dev/docs/api/admin-graphql

Summary

Functions

api_uri(shopify_domain, api_version)

Returns the base URI for the Shopify Admin API.

client(shop, opts \\ [])

Returns an authenticated Tesla client for the Shopify Admin GraphQL API.

ensure_gid(gid, resource)

Ensures the given id is a valid Shopify GID for resource.

query(client, query_string, variables \\ %{})

Sends a GraphQL request to the Shopify Admin API.

trim_gid(gid)

Converts a Shopify GID to its trailing integer id.

unwrap(result, fun)

Unwraps a query/3 result, surfacing transport, HTTP, and GraphQL errors.

Functions

api_uri(shopify_domain, api_version)

@spec api_uri(String.t(), String.t()) :: URI.t()

Returns the base URI for the Shopify Admin API.

client(shop, opts \\ [])

@spec client(
  ExShopifyApp.Shop.authorized(),
  keyword()
) :: Tesla.Client.t()

Returns an authenticated Tesla client for the Shopify Admin GraphQL API.

Options

:api_version - the Shopify API version, defaults to ExShopifyApp.api_version/0.
:debug - when true, logs requests/responses. Defaults to false.

ensure_gid(gid, resource)

@spec ensure_gid(integer() | binary(), binary()) :: binary()

Ensures the given id is a valid Shopify GID for resource.

Already-formed GIDs are returned unchanged.

Examples

iex> ExShopifyApp.Graphql.ensure_gid(1, "shop")
"gid://shopify/Shop/1"

iex> ExShopifyApp.Graphql.ensure_gid("gid://shopify/Shop/1", "shop")
"gid://shopify/Shop/1"

query(client, query_string, variables \\ %{})

@spec query(Tesla.Client.t(), String.t(), map()) :: Tesla.Env.result()

Sends a GraphQL request to the Shopify Admin API.

trim_gid(gid)

@spec trim_gid(String.t()) :: pos_integer()

Converts a Shopify GID to its trailing integer id.

Examples

iex> ExShopifyApp.Graphql.trim_gid("gid://shopify/Shop/1")
1

unwrap(result, fun)

@spec unwrap(Tesla.Env.result(), (map() | nil -> result)) :: result
when result: {:ok, term()} | {:error, term()}

Unwraps a query/3 result, surfacing transport, HTTP, and GraphQL errors.

On a 200 response, a non-empty top-level "errors" array yields {:error, {:graphql, errors}}; otherwise the response's "data" map is passed to fun, which returns the final {:ok, term} | {:error, term}. Non-200 responses collapse to {:error, %Tesla.Env{}} and transport errors to {:error, reason}.