Skip to content

shopify_api 1.0: operations checked against Shopify's schema at compile time - #32

Closed
0xtlt wants to merge 130 commits into
masterfrom
refactor/rework-shopify-api
Closed

0xtlt wants to merge 130 commits into
masterfrom
refactor/rework-shopify-api

Conversation

@0xtlt

@0xtlt 0xtlt commented Oct 22, 2026 •

Copy link
Copy Markdown
Owner

Review entry points: MIGRATION.md for what changes for users, then crates/shopify_api/docs/graphql.md for the new macro. To check it locally: mise install && mise run check.

This PR rewrites the crate toward a 1.0. Operations are checked against Shopify's Admin schema while the crate compiles, and their variables and results are typed.

let data = shopify
    .execute(graphql!(
        "query($first: Int!) { products(first: $first) { nodes { id title totalInventory } } }",
        first = 10,
    ))
    .await?;
// data.products.nodes: Vec<…>, total_inventory: Option<i64>

What changes

  1. graphql!
    • Inline, named (pub mod x = "…", several modules per block), or read from a .graphql file.
    • Input objects are literals checked against the schema: product = { id: id, status: ACTIVE, descriptionHtml: null, vendor?: vendor, metafields: [for m in &rows => { … }] }. input!(MetafieldsSetInput { … }) builds one ahead of the call, as an InputObject whose Rust type is the same for every input! of that GraphQL type. A module's Variables runs directly: shopify.execute(metafields_set::Variables { … }).
    • An Option in a field does not compile (null would clear the field): field?: option leaves it out, field: null sends null, Maybe chooses at run time. Enum values are written bare and checked; raw(…) sends a string unchecked.
    • Values Shopify would not read as written are refused before anything is sent, with Error::InvalidValue { path, reason, detail }, which names the place and the reason, never the value: a Float must be finite, an Int must fit in 32 bits, a non-null JSON must not be null. This holds for literals, input!, a module's Variables (a non-null variable with a default is left out with None, never sent as null) and Operation::variable. An integer literal out of range, alone, negated, in parentheses or in a list […], is a compile error; any other form is checked at run time.
    • Operation::body() returns the exact JSON text execute sends, and Operation::variable_json(name) the text of one variable. Nothing is parsed back: parse it yourself for a serde_json::Value.
    • An unknown field, argument, enum value, directive or variable is a compile error, with a suggestion when a name is close.
    • A deprecated field, argument, input field or enum value is a compiler warning that gives Shopify's reason.
  2. API versions
    • No schema ships with the crates. On the first build, graphql! downloads the Admin schema of the crate's version into graphql/admin.schema.json, to commit. It downloads again when the version changes. Operations are sent to the version they were checked against.
    • By default the version is the latest stable one. It is computed from the date: Shopify releases a version on the first day of each quarter. The next build that recompiles the crate moves to a new version. If the download fails (no network, or the version is not out yet), the build keeps the file it has, else takes the version before.
    • To stay on one version, pin it in Cargo.toml:
      [package.metadata.shopify_api]
      api-version = "2026-07"
    • shopify_api's own operations (bulk, webhooks) are in graphql/operations/*.graphql. They are checked against graphql/internal.schema.json, a 12 KB schema cut down to them, instead of the 876 KB full schema. A test keeps it in sync: mise run schema:internal.
    • shopify-api schema download refreshes the file. It has no --api-version flag. --shop downloads the schema a shop's token sees, and --only cuts the schema down to some operations.
    • shopify-api check validates .graphql files against the same schema graphql! uses.
  3. Client
    • Tokens: static, client credentials, or expiring with refresh. They are renewed in a task of their own, once for all clones, and saved through a TokenStore.
    • Retries: a throttled request waits for what its cost needs, a 429 waits for its Retry-After. Queries are retried after a 5xx or a network failure; mutations never are.
    • Errors hold no secrets and no signed query strings.
  4. Around the client
    • Pagination and bulk operations.
    • Webhooks: verification, and a subscription sync that updates in place and creates before it deletes.
    • OAuth: install link and callback, session tokens, token exchange, app proxies.
    • MockTransport for tests.
  5. Repository
    • A workspace of three crates released together: shopify_api, shopify_api_macros and shopify_api_graphql.
    • mise.toml for the toolchain and tasks; CI runs mise run check and a Rust 1.88 build.
    • The release workflow publishes the three crates in order.

Breaking changes

There are several breaking changes; MIGRATION.md maps every 0.10 API to its replacement. The main ones:

  • Shopify::new(shop, Auth::…) replaces ShopifyConfig.
  • Error replaces ShopifyAPIError.
  • graphql_as replaces graphql::<T>.
  • The warp wrapper, the webhook payload structs, utils and the graphql-client feature are removed.
  • The minimum Rust version is 1.88 and the crates use edition 2024.

Verified

  • mise run check passes: fmt, clippy with -D warnings, tests for every crate and feature, compile-fail tests of the macro's errors, doctests and docs.
  • The tests never reach Shopify: they script it with MockTransport.
  • The full 2026-10 schema is only used by the tests and is not in the published crates (checked with cargo package --list). .cargo/config.toml points the workspace and the compile-fail tests at it.
  • The automatic download was run against Shopify's real endpoint, in a throwaway crate. With no configuration, the first build fetched 2026-10. Pinning 2026-07 switched to it, and removing the pin went back to 2026-10. A version that is not out yet (2027-04) fell back to 2027-01.
  • cargo deny and cargo audit are clean (licenses, bans and sources checked again after adding ureq).

Not verified yet

  • Against a real store. mise run test:live runs ignored tests, given SHOPIFY_TEST_SHOP and either SHOPIFY_TEST_ACCESS_TOKEN or SHOPIFY_TEST_CLIENT_ID and SHOPIFY_TEST_CLIENT_SECRET.
  • The admin HMAC of a query with a repeated parameter (the ids[] of bulk-action links). It follows Shopify's JS library, which joins the values with commas, but was not checked on a real link.
  • Known limits:
    • A literal and input! are checked against the schema of the crate where they are written. rustc's own errors (outside the macros' messages) show an input object as InputObject<hash>.
    • Bulk results are downloaded into memory.
    • A build with no network access needs graphql/admin.schema.json committed. Otherwise it fails with a message saying so.
    • Following the latest version means a field Shopify removes breaks the build without any code change. Pinning api-version avoids it.
    • Cargo does not recompile a crate when the date changes: the move to a new version happens at the next build that recompiles the crate.
    • The macro crate now includes an HTTP client (ureq with rustls), which adds a few seconds to a first, cold build.

Release

Nothing is published. To release, tag the version; the workflow publishes shopify_api_graphql, then shopify_api_macros, then shopify_api at =1.0.0. Publishing a 1.0.0-rc.1 first is an option.

🤖 Generated with Claude Code

0xtlt and others added 30 commits October 22, 2026 08:59
…t compile time

A rewrite around a `graphql!` macro that checks each query or mutation
against the bundled Admin schema (2026-10) and generates the types of its
variables and result. See MIGRATION.md for the move from 0.10.

- Workspace of three crates released together: shopify_api,
  shopify_api_macros and shopify_api_graphql (schema, analyzer, codegen).
- Deprecated fields, arguments, input fields and enum values are compiler
  warnings with Shopify's reason; directives come from the schema.
- Operations go to the version of the schema they were checked against;
  `shopify-api schema download` stores another version, `check` validates
  .graphql files.
- Tokens: static, client credentials, expiring with refresh; renewed in a
  task of its own, once for all clones, saved through a TokenStore.
- Retries: throttling waits for its cost, 429 for Retry-After, queries
  after 5xx or network failures, never a mutation.
- Pagination, bulk operations, webhooks (verification, subscription sync),
  OAuth and session tokens, MockTransport for tests.
- Errors never hold secrets or signed query strings.
- mise.toml for the toolchain and tasks; CI runs `mise run check`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Select the Admin API version with `api-version` in `[package.metadata.shopify_api]`; `graphql!` downloads its schema to `graphql/admin.schema.json` on the next build when it is missing or another version
- `shopify-api schema download` reads the version from Cargo.toml and no longer takes `--api-version`
- Rename the bundled schema file to `admin.schema.json`
- Add `shopify_api_graphql::project` (version lookup, schema source, atomic file writes), behind a `download` feature
- Add `toml` and `ureq` dependencies
- No schema ships with the crates. `graphql!` downloads the schema of the crate's API version on first build and again when the version changes.
- Default version is the latest stable one. `api-version` in `[package.metadata.shopify_api]` pins it.
- `shopify-api schema download --only <files>` keeps only the types and fields those `.graphql` files use.
- Crate operations are checked against a trimmed `graphql/internal.schema.json`, and the Admin schema moves to `crates/shopify_api/graphql/`.
- Add `.cargo/config.toml` pointing `SHOPIFY_GRAPHQL_SCHEMA` at the test schema.
`--cfg docsrs` turns on `feature(doc_cfg)`, which stable Rust rejects, so
the `doc` task failed in CI. docs.rs still sets the flag itself, on nightly.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…work

Pinning a version that is not out yet, or misspelt, failed with "build once
with network access and commit the file", though the download had worked:
Shopify answers such a version with a 400 "Invalid API version".

- The downloads of `shopify_api_graphql::project` return a `DownloadError`,
  whose `UnknownVersion` is that answer.
- `graphql!` then names the version and suggests a released one. Other
  failures keep the advice to build with network access.
- When the latest version is not out and the one before fails too, the
  error is the one before's, the one to fix.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Both v4/v2 ran on the deprecated Node 20 runtime.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
OperationKind::of ended comments at \n only, so "# c\rmutation { … }" read
as a query and was sent again after a 5xx or a network failure. It now
lexes the document: comments end at \r, \n or \r\n (the spec's
LineTerminator), strings and block strings are skipped, and a document it
cannot read to the end (subscription, typo, unbalanced braces) counts as a
mutation, so it is never retried.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A 429's Retry-After was clamped to max_delay (30 s by default), so a
120-300 s cooldown burned every retry early. max_delay now caps only the
computed backoff. A Retry-After longer than the new
RetryPolicy::max_retry_after (5 min by default) is not waited for: the
request ends in Error::Throttled, which now carries that wait in
retry_after (the variant is #[non_exhaustive], so this is additive).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
timestamp=-9223372036854775808 overflowed `now - timestamp` in
verify_query and verify_app_proxy before the signature was checked.
The distance is now an abs_diff, and the timestamp is only read once
the HMAC (constant-time verify_slice) holds. Session token exp/nbf
checks use saturating arithmetic for the same reason.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- testing::GraphqlRequest: manual Debug, access_token shown as [redacted].
- transport::HttpRequest: the URL is shown without its query string, so a
  signed bulk-download address no longer leaks its signature.
- transport::HttpResponse: secret headers (now also Set-Cookie and
  Proxy-Authorization) redacted; a Location header loses its query string.
- bulk::BulkOperation: url and partial_data_url shown without their
  query string.
- CLI DownloadArgs: access token and client secret redacted.

The fields themselves are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
auth.rs spawns the token renewal with tokio::spawn, which needs tokio's
`rt` feature; only `sync` and `time` were declared, so
`cargo check -p shopify_api --no-default-features --lib` failed with
E0425 while reqwest's tokio features hid it in the default build. The
crate now declares `rt`. A new `check:features` mise task builds the
library with no default features and with each feature alone; CI runs
it in its own `features` job, required by "CI is green".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
restricted_to dropped the possible types of interfaces and unions that
no operation selected, so in a cut schema `node { ... on Product { title } }`
made Product the only Node: the fragment always applied and `title`
became `String` instead of `Option<String>`. Decoding an Order then
failed with "missing field title". Interfaces and unions now keep their
whole list of possible types (the names only; the types stay out).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ypes

The analyzer required every selection of a response key to be the same
field with the same arguments, so
`node { ... on Product { label: title } ... on Order { label: name } }`
was refused. Per the spec's FieldsInSetCanMerge, when the two parents are
different object types (never both present), only the shape of the
answer must agree; the field names and arguments may differ. On the same
type or an interface they still must match. The shape check stays
strict: the two types must be the same (same nullability, lists and
named type), so the merged key keeps a single Rust type.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A response that returns a bulk operation's signed url next to an errored
field ended in Error::Graphql, whose derived Debug printed the url.
Debug now lists the keys of the partial data, not their values.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ry-After

Since Retry-After is honored past max_delay, a mocked 429 with
Retry-After: 300 made the test client sleep five minutes. An internal
RetryPolicy flag, set only by testing::client, retries at once; a wait
beyond max_retry_after still ends in Error::Throttled. Production
clients are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
RFC 9110 allows Retry-After as an HTTP date. Only seconds were read, so
a dated 429 was retried after the 1s backoff. The three HTTP-date forms
are now parsed with chrono (already a dependency), the wait is counted
from now, a past date is no wait, and max_retry_after applies as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The spec (All Variable Usages Are Allowed) lets a nullable variable fill a
non-null location only with a non-null default. `$id: ID = null` was
taken as a default and passed. A "gid://..." default is still accepted.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
graphql-parser keeps input objects in a map, so in
{id: "1", title: "old", title: "new"} the first title vanished before
validation while the text sent to Shopify kept both. A small scan of
the text applies Input Object Field Uniqueness before analysis.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`... on ProductVariant { x: image { a: url } } ... on Collection { x: image
{ a: originalSrc } }` was refused: the subselections of `x` merged on Image
and lost the fact that their parents can never both be present. Each
place now carries the parent types above it; two places whose chains
differ by two object types at some depth only need the same shape
(FieldsInSetCanMerge / SameResponseShape). Same type or an interface
still needs the same field and arguments.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
GraphQL Ruby answers a variable that does not validate with its whole
value under extensions.value, so a signed originalSource reached logs
through {:?} of Error::Graphql. GraphqlError's Debug now shows the
message, locations, path, extensions.code and only the names of the
other extensions. errors that are neither a list nor a string keep
their value in extensions.value instead of the message.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Error documented that secrets never appear in it; decode and HTTP errors
did not hold to it.

- Error::Decode (and the token endpoint and variables errors) keep the
  path and the kinds of value, not the values serde quotes:
  'invalid type: string "…"' becomes 'invalid type: string'.
- Error::Http shows at most 1 KiB of the body, with address query
  strings, token-like words (shp…_ prefixes, JWTs, long mixed
  letters and digits) and the values of secret-named entries replaced
  by [redacted], in Display and Debug. The whole body stays available
  through Error::raw_http_body and the new raw_body: RawBody field,
  whose Debug shows its length only.
- The doc of Error states what is guaranteed and what is shown as is.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
chrono's %y pivots at a fixed year, so in 2069 a Retry-After of
'Wednesday, 06-Nov-69 …' did not parse, and later two-digit years
would be read a century off. The century is now chosen from the
current date: the latest year with those two digits that is not more
than 50 years ahead (RFC 9110 §5.6.7). The weekday must still match.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The duplicate input field scan searched a Vec of the fields given so
far, quadratic in the size of one object: 100,000 fields took about
50 s in a debug build, 0.2 s with a HashSet per object. Same results.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Arguments were compared as text, and graphql-parser writes 1.0 as 1
and keeps input objects in a map, so x: f(a: 1) and x: f(a: 1.0), or
{a: 1, b: 2} and {b: 2, a: 1}, were merged while Shopify's GraphQL
Ruby refuses both with fieldConflict.

Values are now compared structurally, by kind (Int, Float, String,
Enum, Boolean, null, variable, list, object): -0.0 is not 0.0, 1.0 is
1.00, a block string is the string it holds. The order of an input
object's fields, which the parser drops, is read back from the text at
the position the parser gives; when it cannot be, the selection is
refused rather than sent. Messages write each value with its kind.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A key selected on two exclusive object types had to name fields of the
same type, so nodes { ... on Product { price: priceRangeV2 { … } }
... on Order { price: totalPriceSet { … } } } was refused although its
answers have one shape. Two places of a key now need the same lists,
nullability and scalar or enum, or two types with subfields; the
subfields of every place are merged, each collected on the type of its
own place, and checked the same way at every depth. Where both places
can be in one answer the field and its arguments must still match.

The merged selection becomes one struct whose fields are those of
every place, optional unless every place selects them; Selection::types
lists the types it is selected on.

Also refuse a field of an object type that has subfields at one place
and none at another ({ shop { name } shop } was accepted).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
is_word keeps '=' and '/' in a word, so 'x=shpat_…' or '/eyJ…' were one
word that did not start like a token. Shopify token prefixes and JWTs
are now found after any non-alphanumeric character of a word.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…input

Text scrubbing kept missing secrets (escaped quotes, JSON \u escapes,
tabs, escaped slashes, map keys, bulk counts, variables errors). Errors
now never put text they did not write in Display, Debug or source():

- Error::Http shows the status, address, content type and body length;
  the body stays in raw_http_body(). The redacted `body` preview is gone.
- Error::Decode: a new path-tracking deserializer (decode.rs) names only
  the fields and variants the Rust type declares (&'static str), writes
  `[key]` for map keys, and describes the mismatch in its own words with
  the line and column. serde's message is in sensitive_detail().
- Error::Variables: one path for Operation::variables, json_variable and
  graphql_raw; the Serialize message is in sensitive_detail().
- Error::Auth: the token endpoint's status and a known OAuth code; its
  answer is in sensitive_detail().
- Bulk counts, ids, statuses and error codes are not echoed.
- InvalidShop/InvalidApiVersion do not show the text given; addresses
  lose their user and password too; GraphQL data/extensions Debug counts
  entries instead of naming them.
- Error::Json and From<serde_json::Error> are gone; redact.rs,
  serde_path_to_error and thiserror are dropped.

A test builds every variant from secret-bearing input and checks
Display, Debug, {:#?} and the source chain.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`draftOrderCreate: draftOrderCreate(...)` skipped the argument scan: the
alias was detected by `alias != name`, so the colon stayed unread and the
scan returned no arguments, and input objects in different orders
compiled although GraphQL Ruby refuses them (fieldConflict). The colon
token now says whether there is an alias.

The analyzer docs say where it is stricter than the specification, and
why.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`Tuesday, 29-Feb-00 08:49:37 GMT` read as 2100-02-29 first, which does
not exist, and the parse gave up before trying 2000: a past Retry-After
fell back to the ordinary backoff instead of no wait. The day, month and
time are now read in a leap year, the century is chosen, then the date
is built.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
0xtlt and others added 27 commits October 26, 2026 10:43
Windows drops a final `.` or space (`x.json.` opens `x.json`), refuses
`<>"|?*` and control characters, and opens a device for `CON`, `NUL`,
`COM1`… whatever the extension: the same `schema` value could name another
file there than on Unix. Every name of the path must now be portable, even
one a later `..` removes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…chema` names

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`analyze_bulk_query` checks a query as Shopify documents bulk queries for
API 2026-10: one top-level connection, five connections at most, nested
two levels deep at most, each selected as `edges { node { … } }`, without
pagination arguments, of `Node` objects, an unaliased `id` on every node
with nested connections, and no two connections of one node that may
return the same type. `check_bulk_mutation` checks one mutation field, not
a bulk operation itself, with one connection at most.

It describes what runs the query: its text without variable definitions,
argument lists that hold a variable set apart, `__typename` on the nodes
of connections that share a parent, the item types with each connection
made a `Vec` of its nodes, and where each line of the results goes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A bulk query builds a `BulkQuery<Item>`, a bulk mutation a
`BulkMutation<Data>` (one line of variables), in the inline form and in
modules, with the variables, literals and `input!` of any operation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`Shopify::bulk_query` starts a `graphql!(bulk(…))` query with
`groupObjects`, waits, and streams its items (`BulkItems`): each
top-level object with the objects of its nested connections in their
lists, placed by `__parentId` and `__typename`, one item held at a time.
`start_bulk_query` and `download_bulk_items` split it.

Shopify takes no variables for a bulk query: `BulkQuery::text` writes them
into the text as GraphQL literals, enum values bare, after the checks of
any operation. An enum value or a field that is not a GraphQL name is
refused (`InvalidValueReason::NotAGraphqlName`).

`Shopify::bulk_mutation` checks and writes every line, stages them, runs,
and streams `BulkMutationResult`s; `start_bulk_mutation` only starts.

Both run at the Admin API version the operation was checked against.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
New files sort first in trybuild's crate numbering: the trait suffixes of
the literal tests change with it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A "Bulk operations" section in the documentation of `graphql!`: the rules
checked, the items and their connections, the variables written into the
text, bulk mutations, and what is not checked. The module docs of `bulk`,
the README, the CHANGELOG and MIGRATION show the typed path first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A bulk query writes an enum variable bare. A `String` or `raw("…")`
holding `null`, `true` or `false` passed the name check and was sent as
`null` or a boolean: another value than the one given. They now fail
with `InvalidValueReason::ReservedEnumValue` before anything is sent; a
real `null` is still written `null`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A bulk query is sent as text written back from what `graphql-parser`
read, and 0.4.1, its latest release, reads `\b` as U+0010 and splits
and indents block strings unlike the specification (a lone `\r`,
Unicode whitespace). Its values carry no position and input objects are
sorted maps, so the original tokens cannot be mapped back reliably.

Each string token of a bulk query is now decoded as the specification
does and compared with what the parser read; a difference is a compile
error that says what to write instead (`\u0008` for `\b`, a quoted
string for a block string).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- A line's `id` places its children only when it is a string: another
  value, such as `id: totalInventory`, no longer fails every line with
  `Error::Decode`. On a node with nested connections, which must select
  `id` itself, another field aliased `id` is refused at compile time.
- Where lines need it, the text sent selects
  `_shopifyApiTypename: __typename` and lines are routed by that key
  alone: a `__typename` of the query, aliased or conditional, is left as
  written instead of merging with an unconditional one. The alias is
  reserved and refused in a bulk query.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
UI tests for a `\b` string, the `_shopifyApiTypename` alias and an `id`
alias beside a nested connection. A constant named like a binding of the
generated code (`__shopify_api_parent`, `__shopify_api_value0`) fails to
compile with E0308: no binding form escapes a constant in scope (`ref`,
`mut` and `x @ _` all give E0530), so the prefix is documented as
reserved and the error pinned, for bulk and literal code alike.

The new files shift trybuild's crate indexes, which the hashed names of
five `literal_*` snapshots follow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Enum values `true`, `false` and `null` in a variable, a list and an
input field; every GraphQL escape and block strings, in constants and
defaults, decoded by the test's own decoder against the value written;
a string variable of every code point; `id` aliases of other types on an
item and a child; routing by `_shopifyApiTypename` beside a conditional
`__typename`. The changelog says what changed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
graphql-parser 0.4 measures the common indentation of a block string in
bytes over any Unicode whitespace, then cuts each line at that byte: a
line indented with U+00A0 (two bytes) beside one indented with U+2003
(three bytes) made `graphql!` panic, bulk or not. Every parse now goes
through `analyze::parse`, which first runs the parser's own indentation
steps on each block string of the source and refuses one whose cut
falls inside a character, at its line and column.

The string lexer of the bulk checks moves to `source`, shared. A test
compares the check with the parser's panics over a grid of whitespace
mixes; UI tests pin the refusal for an ordinary and a bulk operation.
The other UI outputs change because trybuild numbers its test crates in
file order.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`_shopifyApiTypename: products` and `__x: products` were accepted: the
top-level field went straight to `Checker::connection`, without the
`check_key` every field of a node goes through. The docs and changelog
reserve these aliases in the whole bulk query, so the top-level field
is checked as well. Pinned by a unit test and a UI test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The variables section said a `None` is written `null`. A `None` in an
optional field of a module's `Variables` leaves the variable out: its
argument goes, or takes the variable's default. Only a `null` given as a
value (`sort = null`, an inline `Option` that is `None`, a `None` in a
list, `null` or `Maybe::Null` in an input object) is written `null`, and
it replaces the default. The docs and changelog say so; a test pins the
three cases.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…sport

Without `rustls` or `native-tls`, `build` has no transport and the
example failed with `NoTransport` under `--no-default-features`. Its
body now runs only with a transport feature, the text shown unchanged.
`check:features`, which CI's `features` job runs, now also runs the
doctests of `shopify_api` without default features.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ion)`

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
verify_session_token takes only the tokens of Shopify admin again: dest
exactly https://{shop}.myshopify.com, iss exactly its /admin, compared
whole (a prefix let https://s.myshopify.com.evil.example/admin pass).
SessionToken::subject is user_id again.

verify_extension_session_token verifies the tokens of checkout and
customer account UI extensions, which any buyer gets, as an
ExtensionSessionToken (shop, customer, claims) that does not exchange
for a token.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…alEq

So that a progress callback or a retry predicate can be added after 1.0
without a breaking change. They stay Clone, Debug and Default.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…onnections

start_bulk_* only starts and returns the operation; bulk_query* and
bulk_mutation start, wait and read.

- start_bulk_query takes a text (&str, String), GroupObjects(text) for
  groupObjects, or a graphql!(bulk(…)) query or its Variables, through
  the sealed StartBulkQuery trait. run_bulk_query and
  run_bulk_query_grouped(query, bool) are gone.
- run_bulk_mutation and run_bulk_mutation_iter are
  start_bulk_mutation_text, over any iterator (a slice by reference);
  run_bulk_mutation_staged is start_bulk_mutation_staged.
- A typed bulk query asks for groupObjects only when its item has nested
  connections: Shopify documents grouping as slower and more likely to
  time out.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tions

An ignored test, run by mise run test:live, for
products { variants { metafields } media { ... on MediaImage } }: its
items are compared with the raw JSONL regrouped by __parentId. It checks
that Shopify keeps the _shopifyApiTypename alias and the groupObjects
order at the second level. It creates a fixture product, tagged
shopify-api-live-test, when the store has none of that shape.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ackages only

The published macro honoured SHOPIFY_API_INTERNAL_TEST_SCHEMA for every
package, dependencies included. It now applies only when CARGO_PKG_NAME
is shopify_api or shopify_api-tests, the name trybuild gives its
projects; any other crate keeps its own schema. Pinned by a unit test
and by a probe workspace built with the variable set.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ate only

One function names the crate path; every generated item goes through
::shopify_api::__private (Result, Operation, OperationKind, InputObject,
Maybe, bulk::BulkQuery, bulk::BulkMutation). The bulk codegen used
#krate::Result, which a crate re-exporting shopify_api with a Result of
its own shadowed. A probe app that depends only on a facade crate
(extern crate facade as shopify_api) with its own Result, Operation and
bulk now compiles. A future crate = … stays additive.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…with 0.10

MIGRATION: what to do in order when subscribed in XML, verify_hmac marked
JSON only, WebhookSubscription non_exhaustive with new required fields,
wait_for_bulk_operation returns Ok with status Failed while the
start-wait-read calls fail with Error::Bulk, access_token() then token(),
the InvalidApiVersion and Timeout rows, ApiVersion::default() moving from
2026-04 to 2026-10. CHANGELOG: the matching Breaking bullets.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…omer

`ExtensionSessionToken::customer` is the GID of a logged-in customer: the
`sub` of an admin token, a staff member, stays in `claims()`. And
`start_bulk_query` of anything else than a bulk query says so, rather
than asking for `From` (`#[diagnostic::do_not_recommend]`).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@0xtlt 0xtlt closed this Oct 26, 2026
@0xtlt
0xtlt deleted the refactor/rework-shopify-api branch October 26, 2026 14:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant