local-storefront 0.3.0-rc.2 → 0.3.0-rc.4

package/CHANGELOG.md

@@ -3,6 +3,71 @@
 What changed in each version of `lsf`, for someone who uses it. The section of a version is
 what its [GitHub release](https://github.com/0xtlt/local-storefront/releases) says.
 
+## 0.3.0-rc.4 - 2026-11-12
+
+Fourth release candidate of 0.3.0. It fixes the code discounts of 0.3.0-rc.3: their uses, their
+minimums and their one use per customer now follow what Shopify does.
+
+### Fixed
+
+#### The checkout of an app
+
+- **A code discount's `usageLimit` and `appliesOncePerCustomer` hold when checkouts complete at
+  once.** The code is checked again when the order is recorded; when the buyer can no longer use
+  it, the completion answers `422` with the checkout without it and "`<code>` discount code isn't
+  available to you right now".
+- **A free shipping code that takes nothing off is not on the order.** Over its
+  `maximumShippingPrice` for the selected rate, on a cart with nothing to ship, or beaten by a
+  Function's shipping discount, it is no longer in `discount_codes` of the order and its
+  webhooks, and it is not counted as a use.
+- **Minimums count the discounts before them**, as Shopify's help center describes: a free
+  shipping minimum the cart after the product and order discounts, an amount off minimum the
+  items it applies to after the product discounts.
+- **Renaming or deleting a redeemed code no longer resets `appliesOncePerCustomer`.** Uses are
+  matched by discount, not by its codes of the moment.
+
+## 0.3.0-rc.3 - 2026-11-12
+
+Third release candidate of 0.3.0. The local checkout applies the code discounts a backend makes
+through the Admin API, and the session token of checkout and customer account UI extensions is
+the one Shopify gives, signed with the client secret. A backend that read lsf's old token needs
+a change: see Breaking changes.
+
+### Breaking changes
+
+What to change when you upgrade from 0.3.0-rc.2.
+
+- **The session token of a UI extension has Shopify's claims.** `dest` is the shop's bare
+  domain (`local-supply-co.myshopify.com`), no longer lsf's origin; there is no `iss` and no
+  `sid`; it lives five minutes; `sub` is there only when a customer is logged in. It is signed
+  with HS256 and the client secret, so a backend now verifies it as it verifies Shopify's, and
+  one that skipped the verification for lsf can stop doing so.
+
+### Added
+
+#### The checkout of an app
+
+- **`DiscountCodeBasic` and `DiscountCodeFreeShipping` codes apply at the checkout.** A code made
+  with `discountCodeBasicCreate` or `discountCodeFreeShippingCreate` takes an amount or a
+  percentage off the order, off listed products, variants or collections, or off each item, or
+  makes the rates up to `maximumShippingPrice` free in the countries of `destination`. It is taken
+  while the discount is active by its dates, under its `usageLimit`, for a buyer of its `context`
+  (all, listed customers, members of listed segments) who has not used it when it
+  `appliesOncePerCustomer`, and for a cart that meets its `minimumRequirement`. One such code
+  applies per checkout, with the Function discounts. The order and its `orders/create` and
+  `orders/paid` carry it in `discount_codes` and `discount_applications`, and its
+  `asyncUsageCount` goes up. `combinesWith`, buy X get Y codes and a `context` of markets are not
+  read.
+
+### Fixed
+
+#### The checkout of an app
+
+- **`shopify.sessionToken.get()` gives a token a backend can verify.** The page asks lsf for it
+  (`POST /__lsf/extensions/<handle>/session-token`), and lsf signs it with the client secret of
+  the Admin API (`--client-secret`, `SHOPIFY_API_SECRET`, the app's `.env`), which stays on the
+  server. `get()` rejects with the reason when lsf gives no token.
+
 ## 0.3.0-rc.2 - 2026-11-12
 
 Second release candidate of 0.3.0. It fixes what was reported on 0.2.0 and 0.3.0-rc.1, each

package/docs/admin-reference.md

@@ -1079,8 +1079,11 @@ Function by `functionHandle` (or the deprecated `functionId`), which must be a d
 of the app; their `metafields` are the Function's configuration, checked as `metafieldsSet`
 checks them (a definition of the `DISCOUNT` owner type applies). The store sync writes an active
 app discount back to the store data's `checkout.discounts` (its Function, title, first code,
-classes and metafields), so the local checkout runs it. Shopify's own types (basic, buy X get Y,
-free shipping, automatic and code) are kept as records: the local checkout runs Functions only.
+classes and metafields), so the local checkout runs it. Of Shopify's own types, the local
+checkout applies the codes of `DiscountCodeBasic` and `DiscountCodeFreeShipping` itself, and
+counts the orders placed with them in `asyncUsageCount`
+([what the checkout sees](admin.md#what-the-storefront-and-the-checkout-see)); buy X get Y and
+the automatic ones are kept as records.
 Their `summary` is the admin's: what the discount takes off, then its minimum, in the shop's
 money format (`$5.00 off entire order • Minimum purchase of $50.00`, `10% off 2 products`, `Buy
 2 items, get 1 item free`, `Free shipping on all products`), and `shortSummary` its first part.

package/docs/admin.md

@@ -655,7 +655,7 @@ and delivery customizations, validations, cart transforms, fulfillment constrain
 app discounts (`DiscountAutomaticApp`, `DiscountCodeApp`), whether the app created them or the
 store data declared them (`checkout.functions.<handle>.enabled`, `checkout.discounts`). The
 answer counts them (`removedFunctionOwners`). The discounts of Shopify's own types (a
-`DiscountCodeBasic` the app made) stay. While the app is uninstalled, the shop's checkout runs
+`DiscountCodeBasic` the app made) stay, and their codes still apply at the checkout. While the app is uninstalled, the shop's checkout runs
 none of its Functions, whatever a scenario declares or names in its `extensions`: the
 checkout's Functions dialog lists each with "the app is not installed on the shop". A reinstall
 gets none of those objects back, as on Shopify, where a reinstalled app "had to register them
@@ -1624,6 +1624,32 @@ What the backend changes through the Admin API is what the storefront and the
   extensions on the order status page (`appMetafields`, `owner_type = "ORDER"`);
 - an app discount it creates (`discountAutomaticAppCreate`, `discountCodeAppCreate`) runs its
   Function at the checkout, with the metafields it was given, while it is active;
+- a code discount of Shopify's own types it creates (`discountCodeBasicCreate`,
+  `discountCodeFreeShippingCreate`) applies at the checkout once the buyer enters one of its
+  codes, without a Function: an amount or a percentage off the order, off the products,
+  variants and collections it lists (`appliesOnEachItem` included), or free shipping. The
+  checkout takes the code while the discount is `ACTIVE` by its dates, its `usageLimit` is not
+  reached, the buyer is one of its `context` (all buyers, the customers it lists, the members of
+  the segments it lists: a guest is the customer whose email they gave), has not used it when it
+  `appliesOncePerCustomer`, and the cart meets its `minimumRequirement` (the quantity of the
+  items it applies to; a subtotal at the prices the discounts before it left, as on Shopify:
+  the items it applies to after the product discounts for an amount off, the cart after the
+  product and order discounts for free shipping); free shipping makes free the rates up to its
+  `maximumShippingPrice`, to the countries of its `destination`. Otherwise the page says "Enter
+  a valid discount code", and the state's `discountCodes` says why (`reason`). The order carries
+  the code it took something off with (`discountCodes`, a `DiscountCodeApplication`, the
+  allocations), so do the `discount_codes` and `discount_applications` of `orders/create` and
+  `orders/paid` (`type` `shipping` for free shipping), and the discount's `asyncUsageCount` (and
+  its code's) goes up by one at once. A free shipping code that took nothing off (a rate over
+  its maximum, nothing to ship) is neither on the order nor used. The usage limit and the one
+  use per customer are checked again as the order is recorded, so that two checkouts priced at
+  once do not both take the last use: the second completion is refused. A use is the
+  discount's: renaming its code or deleting it (`discountCodeRedeemCodeBulkDelete`) does not
+  give a buyer who used it another one. One code of these types
+  applies per checkout (lsf does not read `combinesWith`), and it stacks with the discounts of
+  the Functions; of the shipping discounts, the best one applies. Not read: a `context` of
+  markets (every buyer), `appliesOnOneTimePurchase` and `appliesOnSubscription`. Buy X get Y
+  codes and Shopify's automatic discounts stay records;
 - the shipping rates of the general delivery profile it changes are the checkout's delivery
   options (see [delivery](admin-reference.md#inventory-transfers-fulfillment-and-delivery));
 - a theme file it writes to the main theme (`themeFilesUpsert`, `themeFilesCopy`,
@@ -1637,7 +1663,7 @@ What the backend changes through the Admin API is what the storefront and the
 | Syncs | Does not sync |
 |---|---|
 | Products: title, handle, description, vendor, type, tags, status and publication, options, variants (price, SKU, barcode, inventory policy, weight), stock per location, media from `files/`, collections and selling plan groups they are in | Orders and what belongs to them (`orderCreate`, draft orders, fulfillments, refunds, returns): the account pages show the orders of the data and of the checkout |
-| Collections: title, handle, description, image, products in order | Discounts that are not app discounts (`DiscountCodeBasic`, …): the local checkout runs Functions only; of an app discount, `combinesWith`, usage limits and every code but the first |
+| Collections: title, handle, description, image, products in order | Discounts of Shopify's own types: the local checkout reads the code ones (`DiscountCodeBasic`, `DiscountCodeFreeShipping`) from the Admin API itself (above), and leaves the others (`…Bxgy`, the automatic ones) out; of an app discount, `combinesWith`, usage limits and every code but the first |
 | Customers: email, names, phone, tags, marketing consent, account state, addresses, their company | Gift cards the Admin API creates (changes to the data's cards sync) |
 | Companies and their locations, pages, blogs and articles, menus, locations, metaobjects and their translations, selling plan groups | SEO, product categories, bundle components and combined listings (a bundle is a product of its own there), collection rules and sources (a changed automated collection becomes a manual one), product feeds, point of sale |
 | Metafields of all of these, of the shop and of markets; markets, their countries and their currency; the published languages | Metafield and metaobject definitions, files, translations of other resources or for a market, publications other than the Online Store; catalogs, price lists, quantity rules, web presences, channels |

package/docs/checkout.md

@@ -1117,6 +1117,37 @@ discounts on the subtotal they left, then shipping. Within a class:
   off −€0.00" while its settings are not set. A candidate of more than 0 that finds nothing left
   to take off (a line another discount made free) is not applied.
 
+**Codes of Shopify's own discount types.** With the [Admin API](admin.md), a code of a
+`DiscountCodeBasic` or a `DiscountCodeFreeShipping` the backend created applies without a
+Function ([what the checkout sees](admin.md#what-the-storefront-and-the-checkout-see)): an
+amount off the order is an order discount, one off listed products, variants or collections (or
+off each item) a product discount, free shipping a shipping discount, and each takes its place
+among the discounts of the Functions by the rules above. The code is checked when the
+checkout is computed: the discount's dates and usage limit, its buyers, one use per customer,
+its minimum, and for free shipping the country of the address (a code is taken before there is
+one). A minimum subtotal counts the prices the discounts before it left, as Shopify's do
+([amount off](https://help.shopify.com/en/manual/discounts/discount-types/percentage-fixed-amount),
+[free shipping](https://help.shopify.com/en/manual/discounts/discount-types/free-shipping),
+"Understanding minimum purchase requirements"): for an amount off, the items it applies to
+after the product discounts of the Functions; for free shipping, the whole cart after the
+product and order discounts. A refused code shows "Enter a valid discount code", and its entry
+of `discountCodes` in the state has a `reason` (`"its minimum purchase is 50.00 USD, and the
+items it applies to come to 32.00 USD after the product discounts"`). One code of these types
+applies per checkout, the first one entered that qualifies: a second is refused, as on Shopify
+when a discount combines with no other (lsf does not read `combinesWith`). Its
+`DiscountApplication` is `ACROSS` (`EACH` off each item), `ALL` for the order and `ENTITLED`
+for listed items; free shipping is 100% off the shipping line, `EACH`.
+
+A free shipping code that takes nothing off (the selected rate costs more than its
+`maximumShippingPrice`, nothing in the cart ships, or a shipping discount of a Function beat it)
+stays applicable on the page, as entered, but it is not the order's: the order does not carry it
+and it is not counted as a use. The codes are checked again as the order is recorded: when
+another order took the last use of the discount (`usageLimit`) or the buyer's one
+(`appliesOncePerCustomer`) after the checkout was priced, the order is not placed. The
+completion answers 422 with the checkout as it now is (the code refused, with its `reason`, the
+price without it) and the error "`<code>` discount code isn't available to you right now" on
+`$.cart.discountCodes`; the buyer pays again for what they now see.
+
 An amount is shared between the lines in proportion to what they cost, to the cent, and the
 allocations of the lines (`discountAllocations`, in the page and for the Functions that run
 later) add up to the discount.
@@ -1298,6 +1329,39 @@ of checkout UI extensions has no such type): an `ORDER` declaration reads nothin
 a warning. Shopify lists `CART` as an owner type of checkout UI extensions only and `ORDER` of
 customer account UI extensions only; lsf takes both on either, as one extension can target both.
 
+### Session tokens
+
+`shopify.sessionToken.get()`, in a checkout or a customer account extension, gives the token
+Shopify gives, which the backend verifies as it verifies Shopify's (`authenticate.public.checkout`
+and `authenticate.public.customerAccount` of Shopify's libraries, `decodeSessionToken`): an
+HS256 JWT signed with the client secret of the [Admin API](admin.md#start)
+(`--client-secret`, `SHOPIFY_API_SECRET` of the environment or of the app's `.env`, else
+`lsf-local-client-secret`; the same without the admin part, without `--client-secret`). Its
+claims are those of shopify.dev's Session Token API, for
+[checkout](https://shopify.dev/docs/api/checkout-ui-extensions/latest/target-apis/platform-apis/session-token-api)
+and [customer account](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/platform-apis/session-token-api)
+extensions:
+
+```json
+{
+  "dest": "local-supply-co.myshopify.com",
+  "aud": "<client id>",
+  "exp": 1794511949,
+  "nbf": 1794511649,
+  "iat": 1794511649,
+  "jti": "7f63880b-b45d-49d4-beb1-af926c85653c",
+  "sub": "gid://shopify/Customer/6523834743460"
+}
+```
+
+`dest` is the shop's domain, bare, as in shopify.dev's example (the session token of the admin
+has `https://`): the `permanent_domain` of the store data, the default shop of the Admin API.
+`aud` is the client id, the token lives five minutes, `jti` is a new UUID each time, and `sub`
+is there only when a customer is logged in (whether the app may read customer data is not
+checked). There is no `iss` and no `sid`. The page asks lsf for the token
+(`POST /__lsf/extensions/<handle>/session-token`, [control API](control-api.md#apps-checkout-and-admin-api))
+and hands it to the extension: the secret never reaches the browser.
+
 ## Run a Function without a server
 
 ```bash
@@ -1505,7 +1569,7 @@ customization runs on them.
 | `shippingAddress` | `address`: `firstName`, `lastName`, `company`, `address1`, `address2`, `city`, `countryCode`, `provinceCode`, `zip`, `phone` | Sets the address. A country of the store becomes the country of the session. A `countryCode` that is not a country (ISO 3166-1 alpha-2, or `XK`, `AC`, `TA` as Shopify takes them; not `ZZ`) is refused and changes nothing. The store data has no shipping zones: any real country is taken. |
 | `deliveryOption` | `group` (`group-1`), `handle` | Chooses a shipping rate. |
 | `paymentMethod` | `handle` | Chooses a payment method. No handle clears it. |
-| `discountCode` | `action` (`add` or `remove`), `code` | Enters or takes back a code. |
+| `discountCode` | `action` (`add` or `remove`), `code` | Enters or takes back a code. Each entered code is in the `discountCodes` of the state, `applicable` or not; a code of a discount of Shopify's own types that was refused has a `reason` ([how discounts stack](#how-discounts-stack)). |
 | `cartLines` | `change`: `addCartLine`, `removeCartLine` or `updateCartLine` of the UI extension API | Changes the cart of the session, the one the theme shows. |
 | `attribute` | `change`: `updateAttribute` or `removeAttribute`, with `key` and `value` | Changes the attributes of the cart. |
 | `note` | `change`: `updateNote` (`note`) or `removeNote` | Changes the note of the cart. |
@@ -1564,7 +1628,10 @@ The browser tests of a theme in CI: [testing](testing.md#in-ci).
 - Discounts have no `conditions` and no combinations: all of them stack, as described in
   [how discounts stack](#how-discounts-stack). Shopify lets the merchant choose which discounts
   combine, and applies the best of those that cannot; here all the product and order discounts
-  combine, and of the shipping discounts the best one applies.
+  combine, and of the shipping discounts the best one applies. Of Shopify's own discount types,
+  only the codes of `DiscountCodeBasic` and `DiscountCodeFreeShipping` apply, one per checkout,
+  and only with the Admin API (which makes them): not buy X get Y, not the automatic ones, not a
+  `context` of markets nor `appliesOnSubscription`.
 - Tax is one rate on the discounted subtotal, with no tax lines.
 - No Storefront API: `query` in an extension rejects. No Customer Account API either: a customer
   account extension reads the account through its `shopify` global only.
@@ -1592,6 +1659,10 @@ store before a release:
 
 - **Discount combinations and conditions**: lsf combines every product and order discount
   ([how discounts stack](#how-discounts-stack)).
+- **Codes of Shopify's own discount types**: one applies per checkout whatever its
+  `combinesWith`, a minimum subtotal counts the prices after every discount before it (Shopify
+  counts only those that combine with it), and a refused code says lsf's reason, where
+  Shopify's checkout has messages of its own.
 - **Currencies and price lists**: a buyer pays in the currency of the country of the shipping
   address (else of the one selected on the storefront), at its market's `rate` or fixed `prices`
   ([localization](data-format.md#localization)); the Functions read that rate as

package/docs/control-api.md

@@ -52,6 +52,7 @@ backend's tests use, then the rest. How a test uses them:
 | `GET /checkout?scenario=<name>` | Opens a checkout for a scenario, in a new session whose cookie it sets. With `--app`. | A redirect |
 | `GET /__lsf/checkout/assets/<file>` | The files of the checkout page, which are in the binary. With `--app`. | The file |
 | `GET /__lsf/extensions/<handle>/<file>` | A file of the build (`dist/`) of a checkout UI extension. With `--app`. | The file |
+| `POST /__lsf/extensions/<handle>/session-token` | What `shopify.sessionToken.get()` gives a checkout or customer account UI extension of the app: a token for the shop (`dest`, its bare domain), the app (`aud`) and the customer logged in in the caller's session (`sub`, absent logged out), valid five minutes, signed with HS256 and the client secret ([session tokens](checkout.md#session-tokens)). The checkout page and the customer account ask it for their extensions; a test can call the backend with it. No CORS: another site cannot read it. `404` for an extension the app does not serve. With `--app`. | `{ "token", "authorization", "shop", "claims" }` |
 | `GET /__lsf/admin` | The [Admin API](admin.md): its shops, their tokens, record counts and webhook subscriptions, the app, the throttle, the mutations, each shop's outbox. | JSON, [below](#admin-api) |
 | `GET /__lsf/graphiql` | GraphiQL on the [Admin API](admin.md#graphiql-in-the-browser): the shops, their tokens and the served versions filled in. | HTML |
 | `DELETE /__lsf/admin` | Puts every shop of the Admin API back to the store data (its clock and its outbox too), forgets the subscriptions the backend made and the tokens OAuth issued, and installs the app again (the printed token works). It revokes every token of the app, those of token exchange too, and sends no `app/uninstalled`: the backend's stored tokens are answered `401` ([reset between runs](admin.md#reset-between-runs)). | `{ "ok": true, "shops": [...] }` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "local-storefront",
-  "version": "0.3.0-rc.2",
+  "version": "0.3.0-rc.4",
   "description": "Run Shopify themes and apps locally, without Shopify: the storefront, a local checkout for Functions and checkout UI extensions, and a local GraphQL Admin API with webhooks, from JSON store data. Made for tests in CI.",
   "keywords": [
     "shopify",
@@ -38,11 +38,11 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "local-storefront-darwin-arm64": "0.3.0-rc.2",
-    "local-storefront-darwin-x64": "0.3.0-rc.2",
-    "local-storefront-linux-arm64": "0.3.0-rc.2",
-    "local-storefront-linux-x64": "0.3.0-rc.2",
-    "local-storefront-win32-arm64": "0.3.0-rc.2",
-    "local-storefront-win32-x64": "0.3.0-rc.2"
+    "local-storefront-darwin-arm64": "0.3.0-rc.4",
+    "local-storefront-darwin-x64": "0.3.0-rc.4",
+    "local-storefront-linux-arm64": "0.3.0-rc.4",
+    "local-storefront-linux-x64": "0.3.0-rc.4",
+    "local-storefront-win32-arm64": "0.3.0-rc.4",
+    "local-storefront-win32-x64": "0.3.0-rc.4"
   }
 }