# `Shopifex.API`
[🔗](https://github.com/ericdude4/shopifex/blob/main/lib/shopifex/api.ex#L1)

Shopify GraphQL Admin API transport.

This is the library's single chokepoint for Admin API calls. Every request
goes through `graphql/3`, which keeps expiring offline access tokens fresh:

- **Proactive refresh** before the call (`Shopifex.Auth.fresh_token/1`): if
  the token will expire within ~5 minutes, refresh now so the request
  doesn't race the expiry.
- **Reactive refresh** after a 401 (`Shopifex.Auth.refresh/1`): if Shopify
  rejects the token anyway (e.g. revoked early), refresh once and retry the
  request once.

This is the strategy Shopify explicitly recommends:
https://shopify.dev/changelog/offline-access-tokens-now-support-expiry-and-refresh

## Error propagation

A refresh failure only short-circuits the request when it's *terminal*
(`Shopifex.Auth.terminal_refresh_error?/1`) — a refresh token that's
expired, missing, or rejected outright by Shopify. In that case `graphql/3`
returns `{:error, {:token_refresh_failed, reason}}` without sending the
GraphQL request at all:

- Proactive terminal failure: no request is sent.
- Reactive terminal failure (refresh after a 401): the same tuple is
  returned instead of the raw `{:error, {401, body}}`.

A *transient* refresh failure (e.g. `:refresh_in_progress`, a 5xx from
Shopify's token endpoint, or a transport error) doesn't block the request:
it's sent with whatever token the shop currently has. The one exception is
`:refresh_in_progress`, which also keeps the reactive 401 retry armed,
since another process might finish the refresh before this request's
token is checked. Any other transient failure disarms the reactive retry
(it would just repeat the same failing attempt), so a 401 in that case
returns the plain `{:error, {401, body}}`.

## What lives here vs. in your app

This module ships only the *transport*. App-specific queries and mutations
(products, inventory, metafields, …) belong in your application — call
`Shopifex.API.graphql/3` from there. The library itself only uses this
transport for webhook subscription and billing mutations.

## API version

The Admin API version is configurable and defaults to `"2026-07"`:

    config :shopifex, :api_version, "2026-07"

`api_version/0` is the single source of truth — webhook and billing code
read it too.

# `api_version`

```elixir
@spec api_version() :: String.t()
```

The configured Shopify Admin API version. Defaults to `"2026-07"`.

# `graphql`

```elixir
@spec graphql(struct(), String.t(), map()) :: {:ok, map()} | {:error, term()}
```

Run a GraphQL query/mutation against the shop's Admin API.

Returns `{:ok, data}` on success, or `{:error, reason}` where `reason` is
one of:

- the GraphQL `errors` list (HTTP 200 with partial failure)
- a `{status, body}` tuple for a non-200/401 response, or a 401 that
  survived the reactive refresh retry
- a transport error (e.g. `%Req.TransportError{}`)
- `{:token_refresh_failed, reason}` when a *terminal* token refresh
  failure stopped the request — see the moduledoc's "Error propagation"
  section

---

*Consult [api-reference.md](api-reference.md) for complete listing*
