# ExShopifySchema

A collection of Elixir schemas for Shopify resources.

## Installation

The package can be installed by adding `ex_shopify_schema`
to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:ex_shopify_schema, "~> <SHOPIFY_VERSION>.patch"}
    # for example: {:ex_shopify_schema, "~> 2025.7.4"}
  ]
end
```

Documentation can be found at <https://hexdocs.pm/ex_shopify_schema>.

## Configuration

You can configure how Ecto types are handled by adding the following to your `config.exs`:

```elixir
config :ex_shopify_schema, :ecto_types,
  enum: :atom,  # or :string
  uri: :struct  # or :string
```

### Available Options

- **`:enum`** - Controls how GraphQL enum values are handled:
  - `:atom` (default) - Enum values are treated as atoms
  - `:string` - Enum values are treated as strings

- **`:uri`** - Controls how URI/URL fields are handled:
  - `:struct` (default) - URI values are returned as `URI.t()` structs
  - `:string` - URI values are returned as plain strings

## Mix Tasks

- **`mix ex_shopify_schema.download.introspection <YYYY-MM>`** — Downloads the
  Shopify GraphQL Admin API introspection JSON for the given version and saves
  it to `priv/graphql/introspections/<YYYY-MM>.json`. Pass `--force` to
  overwrite an existing file.

- **`mix ex_shopify_schema.gen.graphql_schemas`** — Generates the Ecto schema
  modules under `lib/ex_shopify_schema/graphql/` from the introspection JSON
  for the version in `SHOPIFY_VERSION` (or the `SHOPIFY_VERSION` env var). Pass
  `--quiet` to suppress per-file output.

## Releasing

Releases are published to Hex automatically by `.github/workflows/publish.yml`
when a tag is pushed. The workflow builds and publishes one Hex package per
Shopify API version listed in its matrix.

### Patch release (no new Shopify version)

1. Bump `@patch_number` in `mix.exs`.
2. Create a release at <https://github.com/TeamLunaris/ex_shopify_schema/releases>
   with tag `v#{@patch_number}` (e.g. `v6`).
3. The publish workflow runs on the new tag.

### Adding a new Shopify API version

See the Shopify [release schedule](https://shopify.dev/docs/api/usage/versioning#release-schedule)
for available versions.

> **Tip:** If you use [Claude Code](https://docs.claude.com/en/docs/claude-code),
> run `/add-shopify-version <YYYY-MM>` to walk through these steps automatically.
> The skill lives at `.claude/skills/add-shopify-version/`.

1. Download the introspection JSON for the new version:

   ```sh
   mix ex_shopify_schema.download.introspection 2025-10
   ```

2. Bump `@patch_number` in `mix.exs`.
3. Add the new version to the `shopify-version` matrix in
   `.github/workflows/publish.yml`.
4. Create a release at <https://github.com/TeamLunaris/ex_shopify_schema/releases>
   with tag `v#{@patch_number}`.
5. The publish workflow runs on the new tag and publishes a package per matrix
   entry.