Re-land Storefront API 2026-07 migration + fix review issues (v3.0.0)

[qeepcologne]

Re-lands #143 (reverted in #146) with fixes for the issues found in review.

Why a new PR (and not a re-merge of the branch)

The reverted migration commits are still in main's history, so simply re-merging qeepcologne:main would bring only the new fix commits and leave the migration reverted. This branch is a clean re-land committed on top of the current (post-revert) main, so merging it restores the full migration and the fixes in one go.

Addressing the revert notes

The collections are not showing the collection products.

Not a query/parsing bug — I confirmed Collection.fromGraphJson parses real 2026-07 collection products correctly. The example's collection tab hard-coded a filters: {price: {min: 500, max: 600}}, so any store whose products fall outside that range showed an empty collection while the unfiltered product list showed everything. Removed the hard-coded filter (kept a comment showing how to add one).

'CartAddressInput' requires exactly one argument, but 2 were provided when adding a delivery address.

CartAddressInput is a Storefront "one of" input — exactly one field may be present. The generated toJson emitted both copyFromCustomerAddressId and deliveryAddress, so the null one counted as a second argument. Marked both fields @JsonKey(includeIfNull: false) so the unused one is omitted. Verified live: both cartCreate(delivery:) and cartDeliveryAddressesAdd now return userErrors: [] and persist the address.

And a few others.

• Blog/Pages tabs spun forever. Root cause was a missing unauthenticated_read_content scope on the test token (ACCESS_DENIED), but the example also had a bug: the catch cleared the loading flag without setState, so the spinner never went away. Fixed all three fetches to clear via setState and render the actual error (e.g. the scope message) or a "No blogs/pages" empty state.
• Example wouldn't build on a current toolchain (JDK 25 / AGP 9). Updated to Gradle 9.6.1 + AGP 9.3.0 (stable) + built-in Kotlin, and bumped flutter_inappwebview to 6.2.0-beta.3 (the stable line's Android package uses a proguard file AGP 9 removed). Also enabled the .env asset (the example's main.dart loads .env but the asset was commented out, so it never actually loaded config).

Testing

• Ran the example app end-to-end on an Android emulator against a live 2026-07 store — products, variant prices, and categories render; both delivery paths succeed.
• Replayed every document the example uses against a live 2026-07 storefront (products, search, collections, collection-products, full cart lifecycle, delivery) — all clean.
• Fed real responses through the migrated models (Cart, Collection, Products) — nothing dropped on parse.
• Added a regression test for the CartAddressInput one-of serialization. flutter analyze clean; tests pass.

Everything else from #143 is unchanged (the full 2026-07 migration and deprecation cleanup). See #144 for the underlying issue and CHANGELOG for the migration guide.

[imsujan276]

Hi @qeepcologne

Thank you for the update

IN the cart tab in the example app, the line item quantity is not being set. The line item quantity is always 0 on line item add, remove, or add to cart.

Except for this error in cart module, others seems to be good to go.

[qeepcologne]

Thanks for testing — I dug into this one and it turns out to be an example-app bug, not a package bug, and it's not new in this PR. Fixed in the example either way, plus I added a regression test on the package side so the parse path is pinned.

What's actually happening

Shopify creates the line with quantity: 0 when the merchandise isn't purchasable (availableForSale: false), and it reports no userErrors and no errors while doing it. The example's cart tab adds product.productVariants.first.id — the first variant, whether or not it's sellable. On a store whose first variant is out of stock, every add lands as a 0x line, and the +/- buttons then look dead because the server clamps the quantity straight back to 0.

Reproduced against the public Hydrogen demo store (hydrogen-preview.myshopify.com), using this PR's cartLinesAdd document verbatim:

# variant 41007290482744 -> availableForSale: false, quantityAvailable: 0
cartLinesAdd(lines: [{merchandiseId: "...482744", quantity: 1}])
  -> errors: null, userErrors: [], totalQuantity: 0, lines: [{quantity: 0}]

# variant 41007289630776 -> availableForSale: true, quantityAvailable: 10061
cartLinesAdd(lines: [{merchandiseId: "...630776", quantity: 1}])
  -> errors: null, totalQuantity: 1, lines: [{quantity: 1}]

It isn't a regression

I ran the pre-migration document from v2.8.x against the old 2024-07 API on that same store and same out-of-stock variant — identical result, quantity: 0. So this behaviour predates the 2026-07 migration; it just shows up on stores where the first variant happens to be out of stock.

The package parses quantity correctly

To be sure it wasn't us dropping the field, I checked the whole path:

• Raw HTTP responses for cartCreate, cartLinesAdd, cartLinesUpdate on a live 2026-07 store all carry quantity — the documents request it and the server returns it.
• Driving the real client (ShopifyConfig.setConfig → GraphQLClient + normalized cache → ShopifyCart) against a live store: addLineItemsToCart(qty 1) → quantity=1, updateLineItemsInCart(qty 2) → quantity=2, getCartById → quantity=2. All correct.

Added a test (Cart line parses quantity from a cartLinesAdd payload) covering lines.edges -> node -> quantity, including a quantity: 0 out-of-stock line, so a 0 can only ever mean "the server said 0".

What I changed in the example

• addLineItemToCart now picks the first variant with availableForSale == true instead of blindly taking productVariants.first, and refuses with an "out of stock" message if the product has none.
• The product list disables the add button and labels unbuyable products "Out of stock".
• The cart list flags a line whose merchandise is unavailable ("Out of stock — Shopify keeps this line at 0").
• onCartItemUpdate now reports it when Shopify clamps the quantity to less than what was requested, instead of silently looking like the button did nothing.
• Restored the try/catch in addLineItemToCart (it was commented out, so failures there were silently unhandled).

[imsujan276]

@qeepcologne Thank you for your update and contribution to the package. The new version 3.0.0 is now available in pub.dev.