v4.0.0: remove the Checkout and Admin API surfaces, plus parsing and error-handling fixes

[qeepcologne]

Follows on from #147/#148. Branched from current main (including 3.0.1), so it merges cleanly.

Two API surfaces are removed here, which is why this is 4.0.0. The second one is a judgement call and I'd understand pushback — details below, and it's straightforward to drop that commit if you'd rather keep it.

Removals

Checkout API — cannot work on any supported version

Shopify deprecated the Checkout APIs in 2024-04, removed the checkout types in 2024-07, and shut the endpoints off on 1 April 2025. Against a live 2026-07 storefront:

__type(name: "Checkout")   -> null (not in schema)
checkout* mutations        -> none exist on Mutation
get_checkout_* queries     -> "No such type Checkout, so it can't be a fragment condition"

So ShopifyCheckout's 20 methods could only ever fail, with a confusing Field '...' doesn't exist error. Removed: the class, 26 GraphQL documents, the checkout-only models, and JsonHelper.lineItems.

Migration: ShopifyCart + cart.checkoutUrl, which is Shopify's documented replacement. The example already worked this way.

MailingAddress was filed under src/checkout/ but is unrelated to it (it backs Customer.defaultAddress), so it moved to src/mailing_address/ rather than being deleted.

Admin API — a security judgement, not a lifecycle one

To be clear: customerDelete is not deprecated. It is current and working. This is removed on the argument that a Flutter package should not invite Admin credentials into a client at all: a Storefront token is designed to be public and scope-limited, an Admin token grants broad read/write over the whole shop, and anything in a distributed binary can be extracted. Admin work belongs behind a backend.

Removed: adminAccessToken/adminCache on setConfig, the admin client and graphQLClientAdmin, ShopifyAuth.deleteCustomer, and adminAccess on ShopifyCustom.customQuery/customMutation.

This also drops a latent bug — the admin client built its URL from storefrontApiVersion, pinning the independently-versioned Admin API to a Storefront version.

If you'd rather keep Admin support, dropping the remove admin api commit leaves the rest intact. A middle ground would be keeping it with a documented warning plus a separate adminApiVersion.

Fixes

Several of these are silent data loss rather than crashes:

• A failed token renewal signed the user out. _renewAccessToken never checked for errors and fell back to an empty token, which _setShopifyUser read as "no session" and deleted from memory and disk. An offline refresh logged users out with no error and no way back.
• A null quantityAvailable wiped a product's variants. The field is nullable (only returned with unauthenticated_read_product_inventory) but was parsed into a non-null int; _getProductVariants swallowed the error and returned [], so affected stores got products with no variants and price 0.0.
• isAvailableForSale required quantityAvailable > 0, marking purchasable products unavailable both without the inventory scope and on stores that allow overselling — those report a negative quantity while availableForSale stays true. It now follows availableForSale, which Shopify documents as authoritative.
• Metafields were always dropped on unwrapped payloads: _getMetafieldList read json['node']['metafields'] inside the branch only reached when there is no 'node' key, so getProductByHandle/getCollectionByHandle never returned requested metafields.
• Nullable fields threw while parsing — Order.financialStatus/subtotalPrice/customerUrl/totalTax (a fully discounted order has no tax) failed the whole order list; Page.onlineStoreUrl is null for unpublished pages; only id is non-null on MailingAddress.
• Network failures threw a bare String — not an Exception, so it defeated on Exception as well as on ShopifyException and escaped unhandled. With an empty graphqlErrors (sockets, timeouts, 5xx) the thrown value was the empty string, discarding the cause. Now a ShopifyException including linkException.
• getCollectionById reported failures as "not found" — a bad token was indistinguishable from a missing collection, and not-found only worked by letting the parse throw and swallowing it.
• Deprecated currency codes: the symbol table had BYR/STD/VEF but not BYN/STN/VES, so those stores formatted every price as "null12.50".
• Three unreachable fallbacks in ShopifyStore returned values that cannot be constructed and always threw a TypeError from outside the try.
• getAllProductsOnQuery silently ignored its cursor argument (a local shadowed the parameter), so paging restarted from page one.
• getAllOrders sent a read-only query through mutate(), bypassing the cache and ignoring fetchPolicy.
• Pagination loops now stop on an empty page instead of re-issuing the same request forever.
• _setShopifyUser never awaited its SharedPreferences writes.
• ShopifyException and AttributeInput are now exported — both previously needed a src/ import, and updateCartAttributes was uncallable without one.

Other

• Twelve methods narrowed from Future<List<X>?> to Future<List<X>> where no return path could produce null. Existing calls still compile; ?? [] becomes a dead-code warning. Methods that genuinely return null keep the ?.
• json_serializable moved to dev_dependencies — it is codegen-only, and as a runtime dependency it pulled analyzer, build, source_gen etc. into every consuming app. url_launcher removed (unused).
• README signatures corrected against the actual API (7 were stale, 5 of them pre-existing), and addDeliveryAddresses documented.

Checks

flutter analyze --fatal-infos clean on package and example; 17 tests pass, including regressions for each parsing fix above. Documents were replayed against a live 2026-07 storefront, and a schema-driven pass over every field, argument, input-object field and enum value the package uses found no remaining deprecated usage. The example app runs against a live store.

[imsujan276]

Thank you @qeepcologne for this major update.

It looks like you have completely removed the Checkout API in both the package and the example app, which is deprecated and will be removed. But it would be great if you could add its replacement i.e., the Cart API, to imitate the current checkout flow. Checkout is the most important part in the ecommerce app and it would be best for the package to show how the checkout flow can be achieved with an example

Also, as for the admin config, it is an intended config. The android play store needs an feature to be able to delete the account if login/register is in the app. So, we need the admin config and related APIs as it is. It is a optional setup

[qeepcologne]

Thanks for the review and quick response.
Please check again:

• Admin API — reverted the removal;
• Checkout example — the Cart API flow (cart.checkoutUrl → webview) is now a labelled "Checkout · " button in the cart, verified opening the live hosted Shopify checkout on device.
• Login error handling — signInWithEmailAndPassword now surfaces Shopify's real reason (wrong password, unactivated, rate-limit, missing scope) instead of a blanket Invalid credentials.