@webround/commerce 0.4.0 → 0.4.1

package/README.md

@@ -29,15 +29,20 @@ store: `smoke/catalog.smoke.ts`, "how a search combines".
 
 `ShopStore` (`createShopStore`, `shopActions`) is where the state lives: an interface of three methods (`getState`, `subscribe`, `set`), in memory by default; the same state object until
 something really changes (a change that leaves it as it was tells nobody); one that keeps it in the address bar is another implementation. `shopQuestion(catalog, storeData, state,
-context)` is the state made into a `Resource` of the cached catalog (null until the store's data is there). `/react` binds them: `useShop({ catalog, context, initial?, store?,
+context)` is the state made into a `Resource` of the cached catalog (null until the store's data is there). `/react` binds them: `useShop(commerce, { context, initial?, store?,
 keepPrevious? })` gives, each by its name: `state` (what the customer chose), `actions` (what changes it), `question` (the exact `ProductSearch` the catalog is being asked: `state` made a request
-with `context`), `products` and `pagination` (the answer to `question`; `undefined` until it comes), `status`/`error`/`isFetching`/`isStale`/`retry` (how asking the products stands; `keepPrevious` on by
-default, so a listing does not empty at every click), and the store's data (`store`, `collections`, `tags`, `attributes`, `filters`: the lists are `[]` until it is there, `store` is `undefined` until
-then) and `sortOptions`. The store's data alone is `useStoreData(catalog, langCode?)`: the same names plus `status`/`error`/`retry`, and it is the same question `useShop` asks (one request).
-**What `data` is, everywhere in `/react`:** the backends wrap a list or a record as `{ data, pagination… }`; the hooks built on `useResource` (`useOrders`, `useReturnRequests`, `useMyReviews`,
-`useSubscriptions`, a catalog `Resource` given to `useResource`) open that wrapper once, so `result.data` is the list or the record and every other key of the wrapper (`pagination`, `breakdown`) is a
-key of the result beside it (`orders.data`, `orders.pagination`); an answer that is not wrapped (one order) is `data` as it is. The calls of the package itself (`catalog.products.search()`) still give
-what the backend answered, wrapper included: that is the catalog's contract, and what the cache keeps. The text of the search box is the VIEW's (what is being typed); `actions.setSearch` is what is searched (on Enter, or after a pause the component decides): every state
+with `context`), `products` and `pagination` (the answer to `question`), `status`/`error`/`isFetching`/`isStale`/`retry` (how asking the products stands; `keepPrevious` on by default, so a listing does
+not empty at every click), and the store's data (`store`, `collections`, `tags`, `attributes`, `filters`) and `sortOptions`. Every key that comes from the backend is `undefined` until it is there. The
+store's data alone is `useStoreData(commerce, { langCode? })`: the same names plus the asking's, and it is the same question `useShop` asks (one request).
+
+**How data comes out, everywhere (the rule of the shape).** Every read gives an object whose keys NAME what is in it, the same without React and in the hook: `await commerce.catalog.products.search(q)` is
+`{ products, pagination }`, `await commerce.orders.list(q)` is `{ orders, pagination }`, `await commerce.orders.get(id)` is `{ order }`, `useOrders(commerce, q)` is `{ orders, pagination, status, error,
+isFetching, isStale, retry }`: the hook is the call's keys plus how asking stands (the same five fields in every hook that reads from the backend: they win over an answer's own names). Lists are plural
+(`products`, `tags`, `returnRequests`), a single thing singular (`product`, `order`, `returnRequest`, `returnSession`). A customer's reads (`orders`, `returns`, `reviews`) are refused with
+`LOGIN_REQUIRED` when nobody is logged in; what a framework binds to (`Resource`) is at `.resource` (`commerce.orders.resource.list(q)`: `null` when nobody is logged in), as the catalog's is at
+`commerce.catalog.resource`. What changes is a store, and a store gives the same names: `commerce.cart.getState()` and `useCart(commerce)` are `{ lines, count, cart, owner, … }`, `useWishlist(commerce)` is
+`{ wishlist, count, has, … }`, `useAddresses(commerce)` is `{ addresses, … }`, `useAuth(commerce)` is `{ status, customer, challenge, … }`; what changes them is always `actions`. The first argument of every
+hook is `commerce`. The text of the search box is the VIEW's (what is being typed); `actions.setSearch` is what is searched (on Enter, or after a pause the component decides): every state
 change goes back to page 1 and asks the catalog, so a keystroke must not be one.
 
 **The address** (`src/shop/address.ts`, `address-store.ts`; `useShopAddress` in `/react`): the state written in the query string and read back, so a search is a link, "back" goes back through
@@ -61,7 +66,7 @@ Two-factor is covered when the store's key service is there (setup, confirm →
 JavaScript never sees; `credentials: 'include'`) and two cookies the CLIENT writes (so a server render can read them): `wrCsrfToken_<storeId>` (the CSRF token the login gave, 30 days, as long as the
 refresh token; a refresh sends it IN A HEADER, `x-wr-csrf`) and `wrDeviceId_<storeId>` (a year). Cookies go through a port of two functions (`browserCookiePort`, `memoryCookiePort`). `AuthStore`
 (`getState`, `subscribe` like the shop's, `restore`, `signup`, `login`, `verifyTwoFactor`, `logout`, `refresh`, `accessToken`, `authHeaders`): `unknown` → `signedOut` | `signedIn`; a login may be a `challenge`
-(two-factor). It renews the JWT a minute before it ends (a timer) and before it is used; a renewal that could not reach the store is asked again after 2, 4, 8, 16 and 30 seconds, for as long as the JWT is good (a page that loaded with no network: ten asks); a `WakePort` (`browserWakePort`: tab visible again, `online`, `pageshow`) makes it look at the JWT against the clock when the page is back, since a timer does not run while a machine sleeps; `dispose()` stops the timer and the port; **The cart's calls** (`src/cart/`, `createCartApi(http)`; step 1 of the cart): `get`, `addItem`, `updateItem`, `removeItem`, `merge` (these need the JWT: pass the client of `createAuth`), `total` and `verifyPromotions` (with or without one: a guest's lines are in the page and `total` prices them). What the real store does, found by `smoke:cart` and written in the types: `addItem` ADDS to a variant that is already there and answers what happened, not the cart (ask with `get`); a cart has 99 different variants at most and ONE currency and cadence (`CART_LIMIT_REACHED`, `CART_CURRENCY_MISMATCH`, in `CART_ERROR_CODES`); the two totals count only the lines that are AVAILABLE (`isAvailable`); `total` leaves out a variant the store does not have (it does not refuse it) and gives a guest's lines no `id`; `verifyPromotions` with no codes, or with one the store does not know, is 404 `PROMOTION_INVALID`, and wants `cartTotal` as a text of digits; an option of a line is `{ optionName, tagValue, tagValueAlias }` in what `total` answers (the value in the language asked) and `{ optionName, optionValue }` in a customer's cart (the value as it was saved: another thing, not another name). Next: the cart's store (a guest's lines in `localStorage`, the customer's cart, `merge` at login, following `useAuth`), then `useCart`. **The cart's store** (`src/cart/store.ts`, `commerce.cart`; `useCart(commerce)` in `/react`): not logged in, the cart is a guest's: lines kept in the browser (`CartStorage` over a `KeyValuePort`, `localStorage` by default, memory where there is none; key `wrCart_<storeId>`) and priced by the store's `total`. Logged in, it is the customer's and every action is a call of the store's. When a customer logs in or signs up with lines in the browser they are merged with the store's `merge`, and forgotten ONLY once the store has them (a merge that could not be asked for loses nothing and is asked again at the next read; one the store refuses for the lines, 400/404/409/422, is not asked again until the next login; a 403 is asked again: the store answers it right after a signup). State: `lines`/`count` (what the cart IS: known at once) apart from `priced`/`isStale` (what it COSTS: the store's answer, which may be one change behind). Actions (`add`, `setQuantity`, `remove`, `refresh`) go one at a time; a customer's shows at once and is settled with one read when the last is done; a refused one THROWS what the store said and the cart goes back to what the store holds. The cart's `cartTrackingId` (the store's analytics id) is made the first time it is needed, sent with every read and pricing, kept from the guest's cart to the customer's after logging in, and forgotten when the cart is empty. Logging out gives the browser's cart back (empty if its lines were merged): the customer's does not come along. To step a quantity read it from `state.lines`, not from `priced`. A server render says `unknown` and zero items, as the first render in the browser does. **The account** (`src/account/`, `commerce.account`; `useAccount(commerce)` in `/react`): the requests a customer makes about their own account, each one call of the store's. `requestPasswordReset(email)`, `resendVerification()`, `requestAccountDeletion()` only ASK: the store sends an email and the page it leads to (where a password is chosen, an address is verified, a deletion is confirmed) is the store's own. `startTwoFactorSetup()` gives the secret and the address an authenticator app takes; `confirmTwoFactor(code)` turns it on, takes the new session (the customer is `twoFactorEnabled`) and gives the RECOVERY CODES, once (turning it off does not exist in the store). The newsletter is a strategy the store applies and `newsletterStrategy(authState)` tells the screen: a logged-in customer with a verified address is done AT ONCE with their own address (`direct: true`; the session is then read again so `customer.newsletter` says it); a customer whose address is not verified, or a guest (who has to say which address), gets an email with a link (`direct: false`). Asked by someone who is NOT logged in with a REGISTERED address (the store does not look at whether it is verified, for a guest): subscribing sends the owner an email and changes nothing (`direct: false`), unless the address is already subscribed, which it answers `direct: true` (so a guest can learn that an address is subscribed); cancelling sends an email only if it is subscribed, and answers `direct: false` either way. The store limits subscribing and cancelling to 5 a day each per IP. A signup's `newsletter: true` is applied only when the address is verified. Seen on the real store: a logged-in customer already subscribed gets `direct: false` and no email; a guest cancelling an address that was never confirmed gets `direct: false` (an email); a customer cancelling when not subscribed gets `direct: true`. **The addresses** (`src/addresses/`, `commerce.addresses`; `useAddresses(commerce)` in `/react`): a CUSTOMER's addresses are the store's (`/store-customers-addresses`): every action is a call of its and what is shown is what the store holds afterwards (making one the default takes it from the one that was). A GUEST's addresses are kept NOWHERE: in memory, for as long as the page lives (a checkout needs one to ship to and one to bill), with an id of their own (`local-…`); they do not go to a customer when somebody logs in, nor a customer's to a guest. `remember(input)` is what a checkout calls with an address just entered: it keeps it if the customer does not have it already (the same address whatever case and spacing; being a default does not make it another) and gives back the one that is kept. A store keeps 5 addresses for a customer by default (it depends on the plan); the one that goes over is answered with a **429 and no code** ("Too many store_customer_addresss. Limit is 5."), like a rate limit: `dataLimitOf(error)` tells it apart (from the message) and says the limit. **What the customer bought** (`src/orders/`, `commerce.orders`; `useOrders`, `useOrder`, `useSubscriptions`, `useSubscription` in `/react`): the customer's orders, one order and their subscriptions, a page at a time (`page`, `limit` 1 to 100 and 25 by default, `sortBy`, `sortDirection`, `lang`), as RESOURCES of the same cache the catalog is in (`useResource` shows them; a page keeps showing the one before while the next comes). They are the customer's own: the key says whose, there is no resource (`idle` in a hook) when nobody is logged in, and when the customer goes (a logout, another login) what was kept for them is forgotten (`createCustomerResources`, which is what the returns, the reviews and the rest of what a customer reads will be made with). `commerce.orders.refresh()` forgets what was kept (a customer who has just bought wants to see it). An order's items carry `orderItemId`, which a return request names. Held against a real store: the pages (empty, with their pagination), the refusals (404 for what is not the customer's, 400 for a page that is not one) and the cache; the shape of an order that is NOT empty is the types' (the store's code and documentation), to be held against a store that has orders. **Returns** (`src/returns/`, `commerce.returns`; `useReturnRequests`, `useReturnRequest`, `useGuestReturnSession` in `/react`): a CUSTOMER's requests are resources of the cache (their own, as the orders are: `list`, `get`), and `create(input)` / `cancel(id)` forget what was kept so the next read is what the store holds. The `orderItemId`s are the ones of an order's items (`commerce.orders`). Only a `pending` request can be cancelled (the store answers 400 to any other). A GUEST (someone who bought with no account) goes through a LINK: `guest.requestLink({ customerEmail, orderId | reference })` asks the store to email it to the address of the order (it answers the same whether the order exists or not; an order that belongs to an account is refused, 400: its customer logs in). **The link leads to the SITE's page `/returns?token=…`** (the store builds it from the draft's domain): the site needs that page, which reads `token` from the address and shows `useGuestReturnSession(commerce, token)` (the order and its items to choose from); `guest.create({ token, items, reason, shippingAddress, billingAddress })` and `guest.cancel(id, token)` prove who they are by the token (401 for one that is not good or has ended). Held against a real store: what it says to a customer with no orders (an empty page, 404 for an order or a request that is not theirs), to a guest asking for a link, and to a token that is not good; NOT held: a request that is made (it needs an order) and the link itself (it is emailed): their shapes are the types' (the store's code). **The wishlist** (`src/wishlist/`, `commerce.wishlist`; `useWishlist(commerce)` in `/react`): a CUSTOMER's, kept by the store (`/store-customer-wishlists`: the list and one call that is a SWITCH, adding a variant that is not in it and removing one that is). A guest has none: the switch refuses with `LOGIN_REQUIRED` (for the screen to ask them to log in) and the store is not asked. The state is what a heart needs: `variantIds` (which variants are in it, `has(variantId)` in the hook, `isInWishlist`), `count`, `enabled`. A switch shows at once and is settled with what the store holds (read again afterwards); one the store refuses throws what it said and the state goes back to what it was; switches go one at a time. A store can turn the wishlist off (403 "Wishlist is disabled for this store"): `enabled` is `false` from then and the screen can hide its hearts (nothing says it before the first ask: the store's `store_data` does not carry the flag). The store keeps 50 variants for each customer by default; the one that goes over is a 429 with no code (`dataLimitOf`). **Seen on the real store, and it is the store's to fix:** AT the limit even a removal is refused (the same 429): the rule counts the items plus one on every POST of the switch, and removing is the same POST, so a customer who has 50 can not take one out. **Reviews, written** (`src/reviews/`, `commerce.reviews`; `useMyReviews`, `useReviewAbility` in `/react`): a customer's own reviews (`mine`, a resource of the cache: theirs, none when nobody is logged in), and `create(variantId, { rating 1-5, title 2-100, comment 10-2000 })`, `update(id, patch)`, `remove(id)`: the store answers them in `data` and the facade gives that back unwrapped. The store lets only a customer whose address is VERIFIED write (`EMAIL_NOT_VERIFIED`, 400; a change asks for it too, a removal does not), one review for each variant (`REVIEW_ALREADY_EXISTS`, 409) and can turn reviews off (403). `reviewAbility(authState)` / `useReviewAbility` is the hint for the screen (`login`, `verify`, `allowed`: the store decides, the session may be one verification behind). A guest is asked to log in (`LOGIN_REQUIRED`) without asking the store. Writing, changing or removing forgets what was kept of the customer's reviews AND what the catalog kept of that product's reviews (`products.getReviews`; all of them after a removal, which does not say the product), so the next read shows it. Held against a real store: the customer's page (empty), the refusals and the store's rule; NOT held: a review that is written, changed and removed (it needs a verified address, which takes the link in the email): its shape is the types' (the store's code). **What the package does NOT check (decided 14/10).** The store is the source of truth, so the package does not validate what the store validates, and never refuses a request the store might accept: an address, a return, a review, a quantity, a page or a text that is too big or too small is SENT, and the store's 400 comes back as a `CommerceError` (`issues` lists the fields, `code` is what an interface translates). The types (`AddressInput`, `ReviewInput`, `CreateReturnInput`, `CartLineInput`…) are where a screen is told at compile time that something is not right: a type error is a warning, not a request that is not made. This keeps a version of the package working against a store whose rules moved. What stays is not validation: a guest has no wishlist or reviews (`LOGIN_REQUIRED`, the store is not asked: that will not change), `reviewAbility` and `newsletterStrategy` as hints for the screen (the store decides), the guest's cart keeps one line for each variant (adding to a variant adds), and `sameAddress` for `remember`. **`createCommerce({ storeId, commerceApiUrl, catalogApiUrl, … })`** makes what a page needs of ONE store together: `auth` (the session, over the commerce API), `catalog` (cached, over the catalog API: another address) and their `cache`; plain configuration, no environment. **`@webround/commerce-react/site`** is the store of THIS site, made from what it was built with (`wrSiteEnv` of `@webround/core`: `VITE_WR_DRAFT_ID`, which is the `storeId`, `VITE_WR_COMMERCE_API_URL`, `VITE_WR_CATALOG_API_URL`): `import { commerce } from '@webround/commerce-react/site'`, then `useAuth(commerce.auth)`. It is made the first time `commerce.auth`/`.catalog` is read, not when it is imported: a site built without the variables fails where it uses the store and says which are missing (`commerceFromEnv(env, options)` is the same with an environment you give). **`useAuth(auth)`** in `/react` (`auth` is what `createAuth` made, a module of the site makes it once and components import it; no Provider): `{ state, status, customer, challenge, actions }`, `actions` = `signup`, `login`, `verifyTwoFactor`, `cancelChallenge`, `logout` (one object, the same at every render). A call that fails THROWS what the store said: it belongs to the form that made it. The first component that mounts takes the customer back (`restore`, once); a server render says `unknown` and asks nothing; one refresh at a time; a refresh the store REFUSES (401/403) ends the session, one that cannot be reached
+(two-factor). It renews the JWT a minute before it ends (a timer) and before it is used; a renewal that could not reach the store is asked again after 2, 4, 8, 16 and 30 seconds, for as long as the JWT is good (a page that loaded with no network: ten asks); a `WakePort` (`browserWakePort`: tab visible again, `online`, `pageshow`) makes it look at the JWT against the clock when the page is back, since a timer does not run while a machine sleeps; `dispose()` stops the timer and the port; **The cart's calls** (`src/cart/`, `createCartApi(http)`; step 1 of the cart): `get`, `addItem`, `updateItem`, `removeItem`, `merge` (these need the JWT: pass the client of `createAuth`), `total` and `verifyPromotions` (with or without one: a guest's lines are in the page and `total` prices them). What the real store does, found by `smoke:cart` and written in the types: `addItem` ADDS to a variant that is already there and answers what happened, not the cart (ask with `get`); a cart has 99 different variants at most and ONE currency and cadence (`CART_LIMIT_REACHED`, `CART_CURRENCY_MISMATCH`, in `CART_ERROR_CODES`); the two totals count only the lines that are AVAILABLE (`isAvailable`); `total` leaves out a variant the store does not have (it does not refuse it) and gives a guest's lines no `id`; `verifyPromotions` with no codes, or with one the store does not know, is 404 `PROMOTION_INVALID`, and wants `cartTotal` as a text of digits; an option of a line is `{ optionName, tagValue, tagValueAlias }` in what `total` answers (the value in the language asked) and `{ optionName, optionValue }` in a customer's cart (the value as it was saved: another thing, not another name). Next: the cart's store (a guest's lines in `localStorage`, the customer's cart, `merge` at login, following `useAuth`), then `useCart`. **The cart's store** (`src/cart/store.ts`, `commerce.cart`; `useCart(commerce)` in `/react`): not logged in, the cart is a guest's: lines kept in the browser (`CartStorage` over a `KeyValuePort`, `localStorage` by default, memory where there is none; key `wrCart_<storeId>`) and priced by the store's `total`. Logged in, it is the customer's and every action is a call of the store's. When a customer logs in or signs up with lines in the browser they are merged with the store's `merge`, and forgotten ONLY once the store has them (a merge that could not be asked for loses nothing and is asked again at the next read; one the store refuses for the lines, 400/404/409/422, is not asked again until the next login; a 403 is asked again: the store answers it right after a signup). State: `lines`/`count` (what the cart IS: known at once) apart from `cart`/`isStale` (what it COSTS: the cart as the store prices it: the store's answer, which may be one change behind). Actions (`add`, `setQuantity`, `remove`, `refresh`) go one at a time; a customer's shows at once and is settled with one read when the last is done; a refused one THROWS what the store said and the cart goes back to what the store holds. The cart's `cartTrackingId` (the store's analytics id) is made the first time it is needed, sent with every read and pricing, kept from the guest's cart to the customer's after logging in, and forgotten when the cart is empty. Logging out gives the browser's cart back (empty if its lines were merged): the customer's does not come along. To step a quantity read it from `lines`, not from `cart`. A server render says `unknown` and zero items, as the first render in the browser does. **The account** (`src/account/`, `commerce.account`; `useAccount(commerce)` in `/react`): the requests a customer makes about their own account, each one call of the store's. `requestPasswordReset(email)`, `resendVerification()`, `requestAccountDeletion()` only ASK: the store sends an email and the page it leads to (where a password is chosen, an address is verified, a deletion is confirmed) is the store's own. `startTwoFactorSetup()` gives the secret and the address an authenticator app takes; `confirmTwoFactor(code)` turns it on, takes the new session (the customer is `twoFactorEnabled`) and gives the RECOVERY CODES, once (turning it off does not exist in the store). The newsletter is a strategy the store applies and `newsletterStrategy(authState)` tells the screen: a logged-in customer with a verified address is done AT ONCE with their own address (`direct: true`; the session is then read again so `customer.newsletter` says it); a customer whose address is not verified, or a guest (who has to say which address), gets an email with a link (`direct: false`). Asked by someone who is NOT logged in with a REGISTERED address (the store does not look at whether it is verified, for a guest): subscribing sends the owner an email and changes nothing (`direct: false`), unless the address is already subscribed, which it answers `direct: true` (so a guest can learn that an address is subscribed); cancelling sends an email only if it is subscribed, and answers `direct: false` either way. The store limits subscribing and cancelling to 5 a day each per IP. A signup's `newsletter: true` is applied only when the address is verified. Seen on the real store: a logged-in customer already subscribed gets `direct: false` and no email; a guest cancelling an address that was never confirmed gets `direct: false` (an email); a customer cancelling when not subscribed gets `direct: true`. **The addresses** (`src/addresses/`, `commerce.addresses`; `useAddresses(commerce)` in `/react`): a CUSTOMER's addresses are the store's (`/store-customers-addresses`): every action is a call of its and what is shown is what the store holds afterwards (making one the default takes it from the one that was). A GUEST's addresses are kept NOWHERE: in memory, for as long as the page lives (a checkout needs one to ship to and one to bill), with an id of their own (`local-…`); they do not go to a customer when somebody logs in, nor a customer's to a guest. `remember(input)` is what a checkout calls with an address just entered: it keeps it if the customer does not have it already (the same address whatever case and spacing; being a default does not make it another) and gives back the one that is kept. A store keeps 5 addresses for a customer by default (it depends on the plan); the one that goes over is answered with a **429 and no code** ("Too many store_customer_addresss. Limit is 5."), like a rate limit: `dataLimitOf(error)` tells it apart (from the message) and says the limit. **What the customer bought** (`src/orders/`, `commerce.orders`; `useOrders`, `useOrder`, `useSubscriptions`, `useSubscription` in `/react`): the customer's orders, one order and their subscriptions, a page at a time (`page`, `limit` 1 to 100 and 25 by default, `sortBy`, `sortDirection`, `lang`), through the same cache the catalog is in (`await commerce.orders.list(q)` gives `{ orders, pagination }`; the cache's `Resource` is `commerce.orders.resource.list(q)`, which `useOrders` shows; a page keeps showing the one before while the next comes). They are the customer's own: the key says whose, there is no resource (`idle` in a hook) when nobody is logged in, and when the customer goes (a logout, another login) what was kept for them is forgotten (`createCustomerResources`, which is what the returns, the reviews and the rest of what a customer reads will be made with). `commerce.orders.refresh()` forgets what was kept (a customer who has just bought wants to see it). An order's items carry `orderItemId`, which a return request names. Held against a real store: the pages (empty, with their pagination), the refusals (404 for what is not the customer's, 400 for a page that is not one) and the cache; the shape of an order that is NOT empty is the types' (the store's code and documentation), to be held against a store that has orders. **Returns** (`src/returns/`, `commerce.returns`; `useReturnRequests`, `useReturnRequest`, `useGuestReturnSession` in `/react`): a CUSTOMER's requests are resources of the cache (their own, as the orders are: `list`, `get`), and `create(input)` / `cancel(id)` forget what was kept so the next read is what the store holds. The `orderItemId`s are the ones of an order's items (`commerce.orders`). Only a `pending` request can be cancelled (the store answers 400 to any other). A GUEST (someone who bought with no account) goes through a LINK: `guest.requestLink({ customerEmail, orderId | reference })` asks the store to email it to the address of the order (it answers the same whether the order exists or not; an order that belongs to an account is refused, 400: its customer logs in). **The link leads to the SITE's page `/returns?token=…`** (the store builds it from the draft's domain): the site needs that page, which reads `token` from the address and shows `useGuestReturnSession(commerce, token)` (the order and its items to choose from); `guest.create({ token, items, reason, shippingAddress, billingAddress })` and `guest.cancel(id, token)` prove who they are by the token (401 for one that is not good or has ended). Held against a real store: what it says to a customer with no orders (an empty page, 404 for an order or a request that is not theirs), to a guest asking for a link, and to a token that is not good; NOT held: a request that is made (it needs an order) and the link itself (it is emailed): their shapes are the types' (the store's code). **The wishlist** (`src/wishlist/`, `commerce.wishlist`; `useWishlist(commerce)` in `/react`): a CUSTOMER's, kept by the store (`/store-customer-wishlists`: the list and one call that is a SWITCH, adding a variant that is not in it and removing one that is). A guest has none: the switch refuses with `LOGIN_REQUIRED` (for the screen to ask them to log in) and the store is not asked. The state is what a heart needs: `variantIds` (which variants are in it, `has(variantId)` in the hook, `isInWishlist`), `count`, `enabled`. A switch shows at once and is settled with what the store holds (read again afterwards); one the store refuses throws what it said and the state goes back to what it was; switches go one at a time. A store can turn the wishlist off (403 "Wishlist is disabled for this store"): `enabled` is `false` from then and the screen can hide its hearts (nothing says it before the first ask: the store's `store_data` does not carry the flag). The store keeps 50 variants for each customer by default; the one that goes over is a 429 with no code (`dataLimitOf`). **Seen on the real store, and it is the store's to fix:** AT the limit even a removal is refused (the same 429): the rule counts the items plus one on every POST of the switch, and removing is the same POST, so a customer who has 50 can not take one out. **Reviews, written** (`src/reviews/`, `commerce.reviews`; `useMyReviews`, `useReviewAbility` in `/react`): a customer's own reviews (`mine`, a resource of the cache: theirs, none when nobody is logged in), and `create(variantId, { rating 1-5, title 2-100, comment 10-2000 })`, `update(id, patch)`, `remove(id)`: the store answers them in `data` and the facade gives `{ review }` (`remove` gives `{ id }`); the customer's own list is `reviews.list(q)`, `{ reviews, pagination }`. The store lets only a customer whose address is VERIFIED write (`EMAIL_NOT_VERIFIED`, 400; a change asks for it too, a removal does not), one review for each variant (`REVIEW_ALREADY_EXISTS`, 409) and can turn reviews off (403). `reviewAbility(authState)` / `useReviewAbility` is the hint for the screen (`login`, `verify`, `allowed`: the store decides, the session may be one verification behind). A guest is asked to log in (`LOGIN_REQUIRED`) without asking the store. Writing, changing or removing forgets what was kept of the customer's reviews AND what the catalog kept of that product's reviews (`products.getReviews`; all of them after a removal, which does not say the product), so the next read shows it. Held against a real store: the customer's page (empty), the refusals and the store's rule; NOT held: a review that is written, changed and removed (it needs a verified address, which takes the link in the email): its shape is the types' (the store's code). **What the package does NOT check (decided 14/10).** The store is the source of truth, so the package does not validate what the store validates, and never refuses a request the store might accept: an address, a return, a review, a quantity, a page or a text that is too big or too small is SENT, and the store's 400 comes back as a `CommerceError` (`issues` lists the fields, `code` is what an interface translates). The types (`AddressInput`, `ReviewInput`, `CreateReturnInput`, `CartLineInput`…) are where a screen is told at compile time that something is not right: a type error is a warning, not a request that is not made. This keeps a version of the package working against a store whose rules moved. What stays is not validation: a guest has no wishlist or reviews (`LOGIN_REQUIRED`, the store is not asked: that will not change), `reviewAbility` and `newsletterStrategy` as hints for the screen (the store decides), the guest's cart keeps one line for each variant (adding to a variant adds), and `sameAddress` for `remember`. **`createCommerce({ storeId, commerceApiUrl, catalogApiUrl, … })`** makes what a page needs of ONE store together: `auth` (the session, over the commerce API), `catalog` (cached, over the catalog API: another address) and their `cache`; plain configuration, no environment. **`@webround/commerce-react/site`** is the store of THIS site, made from what it was built with (`wrSiteEnv` of `@webround/core`: `VITE_WR_DRAFT_ID`, which is the `storeId`, `VITE_WR_COMMERCE_API_URL`, `VITE_WR_CATALOG_API_URL`): `import { commerce } from '@webround/commerce-react/site'`, then `useAuth(commerce.auth)`. It is made the first time `commerce.auth`/`.catalog` is read, not when it is imported: a site built without the variables fails where it uses the store and says which are missing (`commerceFromEnv(env, options)` is the same with an environment you give). **`useAuth(auth)`** in `/react` (`auth` is what `createAuth` made, a module of the site makes it once and components import it; no Provider): `{ state, status, customer, challenge, actions }`, `actions` = `signup`, `login`, `verifyTwoFactor`, `cancelChallenge`, `logout` (one object, the same at every render). A call that fails THROWS what the store said: it belongs to the form that made it. The first component that mounts takes the customer back (`restore`, once); a server render says `unknown` and asks nothing; one refresh at a time; a refresh the store REFUSES (401/403) ends the session, one that cannot be reached
 does not (it keeps what is good, with `error`); a renewal that comes back after a logout does not bring the session back; logout never throws. `createAuth` makes the store with a client that carries no
 JWT (it asks for the JWT) and gives the site another that carries it. Seen against the real store: it answers a signup/login from inside its transaction, so a call made at once can be refused
 (a refresh: 401 "Invalid Token"; a call with the JWT: 403 "Customer not found"; a logout: 401 "Token mismatch"; the second step of a two-factor login: 404 "Challenge not found"): it
@@ -85,7 +90,7 @@ answer to an older question is thrown away. `isStale` says the answer on show is
 A refused preview throws what the store said, leaves it in `state.error` and keeps the last good one on show as stale. `ensureQuote()` is what a page does by itself: it asks unless the cart is empty or this very question was already asked (by anyone:
 a refusal is not asked again by itself, any number of components can call it); `useCheckout` calls it when the cart or the choices change (`autoQuote: false` turns that off). Nothing is checked here: a cart with no lines, a missing delivery or a
 code that does not exist is sent, and the store's refusal comes back. What the checkout refuses on purpose has a `code` (`CHECKOUT_ERROR_CODES`: `CHECKOUT_BLOCKED` with `{ hookId, code, target }`, `CHECKOUT_HOOK_FAILED`, `SHIPPING_METHOD_UNAVAILABLE`) and
-`checkoutRefusalOf(error)` reads it with its `meta` typed. **Lines with not enough stock** (19/10): the preview does not refuse them, it SETS THEM APART: `quote.unavailable` has them (`QuoteUnavailableLine`: priced like the others but without discounts, with `availableStock`; the whole line even if some units exist), and `quote.items` and `quote.totals` count only what can be bought. The preview is still asked WITH every line (it is what says which ones are unavailable); the payment is not: `pay()` leaves out the lines the last preview said are unavailable (and their delivery method), and when none is left it throws `NOTHING_TO_PAY` without asking the store. A page pays with a fresh preview; the store's own 400 (`Insufficient stock…`, the last unit sold between the preview and the payment) is what is left, and the page asks for the preview again. **The preview describes the lines too** (19/10): each line of `items` and of `unavailable` carries `variantName`, `productName`, `variantSlug`, `skuCode`, `coverUrl`, `options`, `allowedDeliveryMethods` (what `deliveryMethods` can choose from), `availableStock`, `allowBackorder` and `maxOrderQuantity` (`QuoteLinePresentation`): in the v2 flow it is the ONE call that prices a cart and describes it, and it replaces `/cart/total` (the store reads these from OpenSearch like `/cart/total` does). A site that works this way makes its store with `cartPricing: false` (`CartStoreOptions.pricing`; `@webround/commerce-react/site` does): a guest's lines are kept and counted, `priced` stays null and `/cart/total` is never asked; a customer's cart is still read with `/cart/get`, which is where its lines are. **Delivery**: the preview does not need the customer's delivery choice for every line: one without a choice gets the product's default (shipping, else pickup, else none) in the line's `deliveryMethod`, and `allowedDeliveryMethods` says what else it could be; `pay()` sends the customer's choice or, for a line they did not choose for, the one the last preview gave it. **Tracking**: the store's preview sends the cart's analytics event (`cartTrackingId`, as `/cart/total` did), so a site that never calls `/cart/total` is still tracked. **Paying**: `pay(returnUrls?)` builds the order's body from the same choices, `email` (a guest's: who the order is for) and, for an invoice, both codes (a missing one goes as an empty text for the store to
+`checkoutRefusalOf(error)` reads it with its `meta` typed. **Lines with not enough stock** (19/10): the preview does not refuse them, it SETS THEM APART: `quote.unavailable` has them (`QuoteUnavailableLine`: priced like the others but without discounts, with `availableStock`; the whole line even if some units exist), and `quote.items` and `quote.totals` count only what can be bought. The preview is still asked WITH every line (it is what says which ones are unavailable); the payment is not: `pay()` leaves out the lines the last preview said are unavailable (and their delivery method), and when none is left it throws `NOTHING_TO_PAY` without asking the store. A page pays with a fresh preview; the store's own 400 (`Insufficient stock…`, the last unit sold between the preview and the payment) is what is left, and the page asks for the preview again. **The preview describes the lines too** (19/10): each line of `items` and of `unavailable` carries `variantName`, `productName`, `variantSlug`, `skuCode`, `coverUrl`, `options`, `allowedDeliveryMethods` (what `deliveryMethods` can choose from), `availableStock`, `allowBackorder` and `maxOrderQuantity` (`QuoteLinePresentation`): in the v2 flow it is the ONE call that prices a cart and describes it, and it replaces `/cart/total` (the store reads these from OpenSearch like `/cart/total` does). A site that works this way makes its store with `cartPricing: false` (`CartStoreOptions.pricing`; `@webround/commerce-react/site` does): a guest's lines are kept and counted, `cart` stays null and `/cart/total` is never asked; a customer's cart is still read with `/cart/get`, which is where its lines are. **Delivery**: the preview does not need the customer's delivery choice for every line: one without a choice gets the product's default (shipping, else pickup, else none) in the line's `deliveryMethod`, and `allowedDeliveryMethods` says what else it could be; `pay()` sends the customer's choice or, for a line they did not choose for, the one the last preview gave it. **Tracking**: the store's preview sends the cart's analytics event (`cartTrackingId`, as `/cart/total` did), so a site that never calls `/cart/total` is still tracked. **Paying**: `pay(returnUrls?)` builds the order's body from the same choices, `email` (a guest's: who the order is for) and, for an invoice, both codes (a missing one goes as an empty text for the store to
 refuse); it does not redirect (the site sends the customer to `url`) and is asked once per order. Where the customer comes back to is the argument, else `createCommerce({ returnUrls })`, else `browserReturnUrls` (this page's origin: `/checkout/success?clean_cart=true`
 and `/`, what the site has always sent; the store accepts only its own origin, an allowed one or localhost). **After the payment** (the success page): `commerce.cart.clear()` (a guest's lines and tracking id forgotten in the browser; a customer's cart,
 which the store emptied by itself, is read again) or `commerce.checkout.complete()` (that, and the choices and the preview forgotten). `commerce.checkout` needs `checkoutApiUrl`: a store made without it works, and it throws, saying so, where the checkout is read.
@@ -99,8 +104,10 @@ running development API: a hook (it needs an `https` address and the key service
 
 ## Rules that do not bend
 
-1. **The backend's answers are never altered.** Methods return exactly what the API says, `{ data }` envelope included (no unwrapping, no renaming, no "cleaning"). If a
-   field looks wrong, say so; do not fix it here. `wr-commerce-catalog` (the catalog API) is never modified from this repo's work.
+1. **The backend's contract is never altered, and what it answers is only NAMED.** What is asked and what comes back over HTTP is the backend's (`{ data }` envelope included), read as it is. Where an answer comes in
+   (`src/answer.ts`: `opened`, `entity`) the wrapper is opened ONCE and its `data` is given under its own name (`products`, `orders`, `order`…), so what a call gives, what the cache keeps and what a hook shows are
+   the same keys (see "How data comes out"). Nothing else is touched: no field is renamed, "cleaned" or fixed. If a field looks wrong, say so; do not fix it here. `wr-commerce-catalog` (the catalog API) is
+   never modified from this repo's work. (Until 0.4.0 the methods gave the envelope as the backend sent it; Luca decided on 1/11 that one shape everywhere matters more than the envelope.)
 2. **Types come from what the catalog really sends, not from its OpenAPI** (it is wrong in places). `smoke/` checks the types against a real store; when a real answer
    does not match, the TYPE changes (`Format` and nullable `label`/`icon` were found that way).
 3. **No defaults for what the caller chooses.** `include*` options are sent only when given. This is a data layer, not a set of opinions.

package/dist/answer.d.ts

@@ -0,0 +1,11 @@
+/** A wrapped answer (`{ data, pagination… }`) with `data` under its own name: `opened('orders', { data: [...], pagination })` is `{ orders: [...], pagination }`. What else was in the wrapper stays. */
+export declare function opened<K extends string, V, R extends object>(key: K, wire: {
+    data: V;
+} & R): {
+    [P in K]: V;
+} & R;
+/** An answer that came bare (one order) under its own name: `entity('order', order)` is `{ order }`. */
+export declare function entity<K extends string, V>(key: K, value: V): {
+    [P in K]: V;
+};
+//# sourceMappingURL=answer.d.ts.map

package/dist/answer.js

@@ -0,0 +1,13 @@
+// What the package gives back is always an object whose keys say what is in it (`products`, `orders`, `product`, `order`…), the same in a call, in the cache and in what a framework binds to it: never a `data` that
+// has to be opened. The backends do not say it that way (a list is `{ data: [...], pagination }`, a record `{ data: {...} }` or bare), so each call opens what its backend sent ONCE, here, where the answer comes in.
+// The HTTP contract of the backends is not touched: it is read as it is and named on the way in.
+/** A wrapped answer (`{ data, pagination… }`) with `data` under its own name: `opened('orders', { data: [...], pagination })` is `{ orders: [...], pagination }`. What else was in the wrapper stays. */
+export function opened(key, wire) {
+    const { data, ...rest } = wire;
+    return { [key]: data, ...rest };
+}
+/** An answer that came bare (one order) under its own name: `entity('order', order)` is `{ order }`. */
+export function entity(key, value) {
+    return { [key]: value };
+}
+//# sourceMappingURL=answer.js.map

package/dist/cart/store.d.ts

@@ -11,8 +11,8 @@ export interface CartState {
     lines: CartLineInput[];
     /** How many items: the sum of the quantities (what a badge says; known before the store has priced anything). */
     count: number;
-    /** What the store says the cart costs, or null until it said. While `isStale`, it is the answer to the lines before the last change. */
-    priced: Cart | null;
+    /** The cart as the store prices it (the lines with their names, pictures and totals), or null until it said. While `isStale`, it is the answer to the lines before the last change. */
+    cart: Cart | null;
     isStale: boolean;
     /** An action or a call is under way. */
     busy: boolean;
@@ -50,7 +50,7 @@ export interface CartStoreOptions {
     langCode?: () => string | undefined;
     /**
      * Whether a guest's cart is priced with `/cart/total` after every change (default: yes). A site that prices and describes its cart with the checkout's preview (`commerce.checkout`: its lines carry the names, the
-     * pictures, the stock and the totals) says no: the guest's lines are kept and counted, `priced` stays null and `/cart/total` is never called. A customer's cart is still read with `/cart/get`: it is where its lines are.
+     * pictures, the stock and the totals) says no: the guest's lines are kept and counted, `cart` stays null and `/cart/total` is never called. A customer's cart is still read with `/cart/get`: it is where its lines are.
      */
     pricing?: boolean;
 }

package/dist/cart/store.js

@@ -9,7 +9,7 @@ const isDefinite = (error) => error.kind === 'http' && (error.status === 400 ||
 export function createCartStore(options) {
     const { api, auth, storage } = options;
     const lang = () => options.langCode?.();
-    const holder = createStateHolder({ owner: 'unknown', lines: [], count: 0, priced: null, isStale: false, busy: false, error: null, lastMerge: null });
+    const holder = createStateHolder({ owner: 'unknown', lines: [], count: 0, cart: null, isStale: false, busy: false, error: null, lastMerge: null });
     const set = holder.set;
     // Counts the times the cart changed hands: an answer that comes after that is about a cart that is not this one any more
     let epoch = 0;
@@ -27,7 +27,7 @@ export function createCartStore(options) {
         const lines = holder.get().lines;
         if (lines.length === 0) {
             storage.forgetTrackingId();
-            set({ priced: EMPTY_CART, isStale: false, error: null });
+            set({ cart: EMPTY_CART, isStale: false, error: null });
             return;
         }
         // A site that prices with the checkout's preview does not ask `/cart/total`: the lines are all the guest's cart is
@@ -40,7 +40,7 @@ export function createCartStore(options) {
             if (epoch !== mine)
                 return;
             // Lines that changed meanwhile have a pricing of their own coming: this answer is one change behind
-            set({ priced, isStale: holder.get().lines !== lines, error: null });
+            set({ cart: priced, isStale: holder.get().lines !== lines, error: null });
         }
         catch (error) {
             if (epoch === mine)
@@ -96,7 +96,7 @@ export function createCartStore(options) {
             if (priced.items.length === 0)
                 storage.forgetTrackingId();
             const lines = linesOf(priced);
-            set(withLines(lines, { priced, isStale: false, error: mergeError }));
+            set(withLines(lines, { cart: priced, isStale: false, error: mergeError }));
         }
         catch (error) {
             if (epoch === mine)
@@ -105,7 +105,7 @@ export function createCartStore(options) {
     }
     /** What the store holds of a variant in the customer's cart: the line's own id, asking again for the cart first when it is not known (a line just added). */
     async function lineIdOf(variantId) {
-        const find = () => holder.get().priced?.items.find((i) => i.variantId === variantId)?.id;
+        const find = () => holder.get().cart?.items.find((i) => i.variantId === variantId)?.id;
         return find() ?? (await loadCustomer(), find());
     }
     /** A customer's action: what the customer sees changes at once; the call goes in its turn; when the last one is done the cart is read again, so what is shown is what the store holds, a refusal included. */
@@ -128,7 +128,7 @@ export function createCartStore(options) {
         epoch++;
         pricing = null;
         const lines = storage.lines();
-        set(withLines(lines, { owner: 'guest', priced: null, isStale: lines.length > 0, error: null, lastMerge: null }));
+        set(withLines(lines, { owner: 'guest', cart: null, isStale: lines.length > 0, error: null, lastMerge: null }));
         void schedulePricing();
     }
     function toCustomer() {
@@ -137,7 +137,7 @@ export function createCartStore(options) {
         mergeRefused = false;
         mergeError = null;
         // The guest's lines stay in sight until the merge is done: the badge does not blink to 0
-        set({ owner: 'customer', priced: null, isStale: true, error: null });
+        set({ owner: 'customer', cart: null, isStale: true, error: null });
         void queue.run(loadCustomer);
     }
     const following = followAuth(auth, { current: () => holder.get().owner, toGuest, toCustomer });
@@ -210,7 +210,7 @@ export function createCartStore(options) {
             pricing = null;
             storage.clearLines();
             storage.forgetTrackingId();
-            set(withLines([], { priced: EMPTY_CART, isStale: false, error: null }));
+            set(withLines([], { cart: EMPTY_CART, isStale: false, error: null }));
         },
         dispose: following.stop,
     };

package/dist/catalog/cached.d.ts

@@ -2,22 +2,22 @@ import { type Cache } from '../cache.js';
 import { type Resource } from '../resource.js';
 import type { HttpClient } from '../http.js';
 import { type Catalog } from './catalog.js';
-import type { ProductByIdInput, ProductBySlugInput, ProductDetailResponse, ProductPage, ProductRelatedInput, ProductReviewsInput, ProductSearch, ReviewPage, StoreDataResponse } from './types.js';
+import type { ProductAnswer, ProductByIdInput, ProductBySlugInput, ProductPage, ProductRelatedInput, ProductReviewsInput, ProductSearch, ReviewPage, StoreData } from './types.js';
 /** What can be forgotten from the cache: one of the catalog's calls. */
 export type CatalogCall = 'products.search' | 'products.getBySlug' | 'products.getById' | 'products.getReviews' | 'products.getRelated' | 'storeData.get';
 export type { Resource };
 export interface CatalogResources {
     products: {
         search(input: ProductSearch): Resource<ProductPage>;
-        getBySlug(variantSlug: string, input: ProductBySlugInput): Resource<ProductDetailResponse>;
-        getById(id: string, input: ProductByIdInput): Resource<ProductDetailResponse>;
+        getBySlug(variantSlug: string, input: ProductBySlugInput): Resource<ProductAnswer>;
+        getById(id: string, input: ProductByIdInput): Resource<ProductAnswer>;
         getReviews(id: string, input?: ProductReviewsInput): Resource<ReviewPage>;
         getRelated(id: string, input: ProductRelatedInput): Resource<ProductPage>;
     };
     storeData: {
         get(input?: {
             langCode?: string;
-        }): Resource<StoreDataResponse>;
+        }): Resource<StoreData>;
     };
 }
 /**

package/dist/catalog/products.d.ts

@@ -1,25 +1,25 @@
 import type { HttpClient } from '../http.js';
-import type { CallOptions, ProductByIdInput, ProductBySlugInput, ProductDetailResponse, ProductPage, ProductRelatedInput, ProductReviewsInput, ProductSearch, ReviewPage } from './types.js';
+import type { CallOptions, ProductAnswer, ProductByIdInput, ProductBySlugInput, ProductPage, ProductRelatedInput, ProductReviewsInput, ProductSearch, ReviewPage } from './types.js';
 export interface ProductsApi {
     /**
-     * `POST /public/products`: the store's products, filtered, sorted and paginated as asked. Nothing is added to what is asked (no page, no limit, no sorting): the server's own
+     * `POST /public/products`: the store's products, filtered, sorted and paginated as asked: `{ products, pagination }`. Nothing is added to what is asked (no page, no limit, no sorting): the server's own
      * defaults apply to what is left out. The body goes out in its canonical form (keys and lists in order), so the same search is always the same request.
      */
     search(input: ProductSearch, options?: CallOptions): Promise<ProductPage>;
     /**
-     * `POST /public/products/by-slug/{variantSlug}`: the product that has a variant with this slug, with all it has. A product has no slug: it is the VARIANT's. What is loaded with it is for
+     * `POST /public/products/by-slug/{variantSlug}`: the product that has a variant with this slug, with all it has: `{ product }`. A product has no slug: it is the VARIANT's. What is loaded with it is for
      * `input`'s `include*` to say.
      */
-    getBySlug(variantSlug: string, input: ProductBySlugInput, options?: CallOptions): Promise<ProductDetailResponse>;
-    /** `POST /public/products/{id}`: the product with this id, with all it has. */
-    getById(id: string, input: ProductByIdInput, options?: CallOptions): Promise<ProductDetailResponse>;
+    getBySlug(variantSlug: string, input: ProductBySlugInput, options?: CallOptions): Promise<ProductAnswer>;
+    /** `POST /public/products/{id}`: the product with this id, with all it has: `{ product }`. */
+    getById(id: string, input: ProductByIdInput, options?: CallOptions): Promise<ProductAnswer>;
     /**
-     * `POST /public/products/{id}/reviews`: the product's reviews, a page of them, with how many there are for each grade. The id is the product's (a UUID: the catalog refuses anything else with a 400).
+     * `POST /public/products/{id}/reviews`: the product's reviews, a page of them, with how many there are for each grade: `{ reviews, pagination, breakdown }`. The id is the product's (a UUID: the catalog refuses anything else with a 400).
      * A product with no reviews is an empty page, not an error.
      */
     getReviews(id: string, input?: ProductReviewsInput, options?: CallOptions): Promise<ReviewPage>;
     /**
-     * `POST /public/products/{id}/related`: the products related to this one (up to ten, the most relevant first), in the same shape as a search's. The id is the product's (a UUID).
+     * `POST /public/products/{id}/related`: the products related to this one (up to ten, the most relevant first), in the same shape as a search's: `{ products, pagination }`. The id is the product's (a UUID).
      * A product with nothing related is an empty page, not an error.
      */
     getRelated(id: string, input: ProductRelatedInput, options?: CallOptions): Promise<ProductPage>;

package/dist/catalog/products.js

@@ -1,12 +1,16 @@
+import { entity, opened } from '../answer.js';
 import { canonicalize } from '../canonical.js';
 import { named } from './named.js';
 export function createProductsApi(http) {
+    const products = async (request) => opened('products', await request);
+    const product = async (request) => entity('product', (await request).data);
+    const reviews = async (request) => opened('reviews', await request);
     return {
-        search: (input, options) => http.request({ method: 'POST', path: '/public/products', body: canonicalize(input), signal: options?.signal }),
-        getBySlug: (variantSlug, input, options) => http.request({ method: 'POST', path: `/public/products/by-slug/${named('a variant slug', variantSlug)}`, body: canonicalize(input), signal: options?.signal }),
-        getById: (id, input, options) => http.request({ method: 'POST', path: `/public/products/${named('an id', id)}`, body: canonicalize(input), signal: options?.signal }),
-        getRelated: (id, input, options) => http.request({ method: 'POST', path: `/public/products/${named('an id', id)}/related`, body: canonicalize(input), signal: options?.signal }),
-        getReviews: (id, input, options) => http.request({ method: 'POST', path: `/public/products/${named('an id', id)}/reviews`, body: canonicalize(input ?? {}), signal: options?.signal }),
+        search: (input, options) => products(http.request({ method: 'POST', path: '/public/products', body: canonicalize(input), signal: options?.signal })),
+        getBySlug: (variantSlug, input, options) => product(http.request({ method: 'POST', path: `/public/products/by-slug/${named('a variant slug', variantSlug)}`, body: canonicalize(input), signal: options?.signal })),
+        getById: (id, input, options) => product(http.request({ method: 'POST', path: `/public/products/${named('an id', id)}`, body: canonicalize(input), signal: options?.signal })),
+        getRelated: (id, input, options) => products(http.request({ method: 'POST', path: `/public/products/${named('an id', id)}/related`, body: canonicalize(input), signal: options?.signal })),
+        getReviews: (id, input, options) => reviews(http.request({ method: 'POST', path: `/public/products/${named('an id', id)}/reviews`, body: canonicalize(input ?? {}), signal: options?.signal })),
     };
 }
 //# sourceMappingURL=products.js.map

package/dist/catalog/store-data.d.ts

@@ -1,13 +1,13 @@
 import type { HttpClient } from '../http.js';
-import type { CallOptions, StoreDataResponse } from './types.js';
+import type { CallOptions, StoreData } from './types.js';
 export interface StoreDataApi {
     /**
-     * `GET /public/store_data`: what the store is made of for a customer: its settings, the collections, the filters, the tags and the attributes to filter and sort by. The answer is
-     * the catalog's own (`{ data: … }`), unchanged. `langCode` is the language the names come in: `default` (or none) is the store's default language, and one the store does not use gets it too.
+     * `GET /public/store_data`: what the store is made of for a customer: `{ store, collections, filters, tags, attributes }` (its settings, the collections, the filters, and the tags and attributes to filter and sort by).
+     * The catalog sends it as `{ data: … }`: it is opened here. `langCode` is the language the names come in: `default` (or none) is the store's default language, and one the store does not use gets it too.
      */
     get(input?: {
         langCode?: string;
-    }, options?: CallOptions): Promise<StoreDataResponse>;
+    }, options?: CallOptions): Promise<StoreData>;
 }
 export declare function createStoreDataApi(http: HttpClient): StoreDataApi;
 //# sourceMappingURL=store-data.d.ts.map

package/dist/catalog/store-data.js

@@ -1,6 +1,6 @@
 export function createStoreDataApi(http) {
     return {
-        get: (input, options) => http.request({ path: '/public/store_data', query: { langCode: input?.langCode }, signal: options?.signal }),
+        get: async (input, options) => (await http.request({ path: '/public/store_data', query: { langCode: input?.langCode }, signal: options?.signal })).data,
     };
 }
 //# sourceMappingURL=store-data.js.map

package/dist/catalog/types.d.ts

@@ -179,9 +179,9 @@ export interface Pagination {
     total: number;
     totalPages: number;
 }
-/** The answer of `POST /public/products`. */
+/** The answer of `POST /public/products` (and of the related products): the catalog sends the list as `data`, here it is `products`. */
 export interface ProductPage {
-    data: ProductSummary[];
+    products: ProductSummary[];
     pagination: Pagination;
 }
 export interface Review {
@@ -197,9 +197,9 @@ export interface Review {
     createdAt: string | null;
     updatedAt: string | null;
 }
-/** The answer of `POST /public/products/{id}/reviews`, as the catalog sends it. */
+/** The answer of `POST /public/products/{id}/reviews`: the catalog sends the list as `data`, here it is `reviews`. */
 export interface ReviewPage {
-    data: Review[];
+    reviews: Review[];
     pagination: Pagination;
     /** How many reviews there are for each grade, over all of the product's reviews that match `rating` (a grade nobody gave is not there). */
     breakdown: Partial<Record<'1' | '2' | '3' | '4' | '5', number>>;
@@ -315,9 +315,9 @@ export interface ProductDetail {
     /** All the visible variants. */
     variants: VariantDetail[];
 }
-/** The answer of `POST /public/products/by-slug/{slug}` and `POST /public/products/{id}`, as the catalog sends it. */
-export interface ProductDetailResponse {
-    data: ProductDetail;
+/** The answer of `POST /public/products/by-slug/{slug}` and `POST /public/products/{id}`: the catalog sends the product as `data`, here it is `product`. */
+export interface ProductAnswer {
+    product: ProductDetail;
 }
 /** The store's own settings. What the server has not got comes with its default (`EUR`, `once`, `IT`, `default`, a list with the default one). */
 export interface StoreSettings {
@@ -407,6 +407,7 @@ export interface StoreFilter {
     type: 'price' | 'date' | 'number';
     conditions: StoreFilterCondition[];
 }
+/** The answer of `GET /public/store_data` (the catalog sends it as `data`: it is opened, these keys are the answer). */
 export interface StoreData {
     store: StoreSettings;
     tags: StoreTag[];
@@ -414,8 +415,4 @@ export interface StoreData {
     collections: StoreCollection[];
     filters: StoreFilter[];
 }
-/** The answer of `GET /public/store_data`, as the catalog sends it. */
-export interface StoreDataResponse {
-    data: StoreData;
-}
 //# sourceMappingURL=types.d.ts.map

package/dist/customer-resources.d.ts

@@ -2,6 +2,10 @@ import { type Cache } from './cache.js';
 import type { CallOptions } from './catalog/types.js';
 import type { AuthStore } from './auth/store.js';
 import { type Resource, type ResourceIdentity } from './resource.js';
+/** What a customer's call says when nobody is logged in: what the store itself answers to a request with no customer (the same code the wishlist and the reviews use). */
+export declare const CUSTOMER_LOGIN_REQUIRED = "LOGIN_REQUIRED";
+/** A customer's resource, answered: its answer, or (nobody is logged in: there is no resource) the refusal, so a call never gives `null` where a framework's binding would. */
+export declare function loadForCustomer<T>(resource: Resource<T> | null): Promise<T>;
 export interface CustomerResources {
     /** A question about the logged-in customer's data, or null when nobody is. `subject` is what the call is about (an order's id). */
     resource<T>(call: string, subject: string | undefined, params: unknown, fetch: (options: CallOptions) => Promise<T>): Resource<T> | null;

package/dist/customer-resources.js

@@ -1,5 +1,14 @@
 import { cachePrefix } from './cache.js';
+import { CommerceError } from './errors.js';
 import { createResourceFactory } from './resource.js';
+/** What a customer's call says when nobody is logged in: what the store itself answers to a request with no customer (the same code the wishlist and the reviews use). */
+export const CUSTOMER_LOGIN_REQUIRED = 'LOGIN_REQUIRED';
+/** A customer's resource, answered: its answer, or (nobody is logged in: there is no resource) the refusal, so a call never gives `null` where a framework's binding would. */
+export function loadForCustomer(resource) {
+    return resource
+        ? resource.load()
+        : Promise.reject(new CommerceError({ kind: 'http', status: 401, code: CUSTOMER_LOGIN_REQUIRED, message: 'Log in to see this.' }));
+}
 export function createCustomerResources(options) {
     const { cache, identity, auth } = options;
     const make = createResourceFactory(cache, identity);

package/dist/index.d.ts

@@ -28,5 +28,5 @@ export * from './wishlist/index.js';
 export * from './shop/index.js';
 export type { ProductsApi } from './catalog/products.js';
 export type { StoreDataApi } from './catalog/store-data.js';
-export type { AssetDetail, AssetSummary, AssetType, AttributeDetail, AttributeSummary, Availability, CallOptions, Format, OptionDetail, OptionValueDetail, Pagination, PriceDetail, PriceRange, ProductByIdInput, ProductBySlugInput, ProductDetail, ProductDetailInput, ProductDetailResponse, ProductLoad, ProductPage, ProductRelatedInput, ProductReviewsInput, ProductSearch, ProductSortField, ProductSummary, Review, ReviewPage, ReviewStats, SortDirection, StoreAttribute, StoreCollection, StoreData, StoreDataResponse, StoreFilter, StoreFilterCondition, StoreSettings, StoreTag, StoreTagValue, TagDetail, TagSummary, TagType, TagValueDetail, TagValueSummary, ValueFormat, VariantDetail, VariantSummary, } from './catalog/types.js';
+export type { AssetDetail, AssetSummary, AssetType, AttributeDetail, AttributeSummary, Availability, CallOptions, Format, OptionDetail, OptionValueDetail, Pagination, PriceDetail, PriceRange, ProductAnswer, ProductByIdInput, ProductBySlugInput, ProductDetail, ProductDetailInput, ProductLoad, ProductPage, ProductRelatedInput, ProductReviewsInput, ProductSearch, ProductSortField, ProductSummary, Review, ReviewPage, ReviewStats, SortDirection, StoreAttribute, StoreCollection, StoreData, StoreFilter, StoreFilterCondition, StoreSettings, StoreTag, StoreTagValue, TagDetail, TagSummary, TagType, TagValueDetail, TagValueSummary, ValueFormat, VariantDetail, VariantSummary, } from './catalog/types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/orders/api.d.ts

@@ -1,16 +1,16 @@
 import type { HttpClient } from '../http.js';
 import type { CallOptions } from '../catalog/types.js';
 import type { AccessTokenOptions } from '../auth/api.js';
-import type { Order, OrderPage, PageQuery, Subscription, SubscriptionPage } from './types.js';
+import type { OrderAnswer, OrderPage, PageQuery, SubscriptionAnswer, SubscriptionPage } from './types.js';
 export interface OrderApi {
     /** `GET /store-customer-orders`: the customer's orders, a page at a time (the newest first). */
     list(input?: PageQuery, options?: CallOptions & AccessTokenOptions): Promise<OrderPage>;
     /** `GET /store-customer-orders/:id`: one order, with its items. 404 for one that is not the customer's. */
-    get(id: string, options?: CallOptions & AccessTokenOptions): Promise<Order>;
+    get(id: string, options?: CallOptions & AccessTokenOptions): Promise<OrderAnswer>;
     /** `GET /store-customer-orders/subscriptions`: the customer's subscriptions (what they pay for again and again), a page at a time. */
     listSubscriptions(input?: PageQuery, options?: CallOptions & AccessTokenOptions): Promise<SubscriptionPage>;
     /** `GET /store-customer-orders/subscriptions/:id`. */
-    getSubscription(id: string, options?: CallOptions & AccessTokenOptions): Promise<Subscription>;
+    getSubscription(id: string, options?: CallOptions & AccessTokenOptions): Promise<SubscriptionAnswer>;
 }
 export declare function createOrderApi(http: HttpClient): OrderApi;
 //# sourceMappingURL=api.d.ts.map

package/dist/orders/api.js

@@ -1,13 +1,15 @@
-// The calls of commerce-core that are about what a customer bought (`/store-customer-orders`), each asking one thing and giving back what the store answers, unchanged. All need the JWT of the customer, and all read.
+import { entity, opened } from '../answer.js';
+// The calls of commerce-core that are about what a customer bought (`/store-customer-orders`), each asking one thing and giving back what the store answers, named: `{ orders, pagination }`, `{ order }`… (the store sends a page
+// as `{ data, pagination }` and an order bare: opened here, once). All need the JWT of the customer, and all read.
 const bearer = (options) => (options?.accessToken ? { Authorization: `Bearer ${options.accessToken}` } : {});
 const part = (id) => encodeURIComponent(id);
 const query = (q) => ({ page: q?.page, limit: q?.limit, sortBy: q?.sortBy, sortDirection: q?.sortDirection, lang: q?.lang });
 export function createOrderApi(http) {
     return {
-        list: (input, options) => http.request({ path: '/store-customer-orders', query: query(input), headers: bearer(options), signal: options?.signal }),
-        get: (id, options) => http.request({ path: `/store-customer-orders/${part(id)}`, headers: bearer(options), signal: options?.signal }),
-        listSubscriptions: (input, options) => http.request({ path: '/store-customer-orders/subscriptions', query: query(input), headers: bearer(options), signal: options?.signal }),
-        getSubscription: (id, options) => http.request({ path: `/store-customer-orders/subscriptions/${part(id)}`, headers: bearer(options), signal: options?.signal }),
+        list: async (input, options) => opened('orders', await http.request({ path: '/store-customer-orders', query: query(input), headers: bearer(options), signal: options?.signal })),
+        get: async (id, options) => entity('order', await http.request({ path: `/store-customer-orders/${part(id)}`, headers: bearer(options), signal: options?.signal })),
+        listSubscriptions: async (input, options) => opened('subscriptions', await http.request({ path: '/store-customer-orders/subscriptions', query: query(input), headers: bearer(options), signal: options?.signal })),
+        getSubscription: async (id, options) => entity('subscription', await http.request({ path: `/store-customer-orders/subscriptions/${part(id)}`, headers: bearer(options), signal: options?.signal })),
     };
 }
 //# sourceMappingURL=api.js.map

package/dist/orders/index.d.ts

@@ -1,6 +1,6 @@
 export { createOrderApi } from './api.js';
 export type { OrderApi } from './api.js';
 export { createOrders } from './orders.js';
-export type { Orders } from './orders.js';
-export type { Order, OrderAddress, OrderItem, OrderPage, Page, PageInfo, PageQuery, Subscription, SubscriptionPage } from './types.js';
+export type { Orders, OrdersResources } from './orders.js';
+export type { Order, OrderAddress, OrderAnswer, OrderItem, OrderPage, Page, PageInfo, PageQuery, Subscription, SubscriptionAnswer, SubscriptionPage } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/orders/orders.d.ts

@@ -1,14 +1,27 @@
-import type { CustomerResources } from '../customer-resources.js';
+import { type CustomerResources } from '../customer-resources.js';
 import type { Resource } from '../resource.js';
 import type { OrderApi } from './api.js';
-import type { Order, OrderPage, PageQuery, Subscription, SubscriptionPage } from './types.js';
-export interface Orders {
+import type { OrderAnswer, OrderPage, PageQuery, SubscriptionAnswer, SubscriptionPage } from './types.js';
+export interface OrdersResources {
     list(query?: PageQuery): Resource<OrderPage> | null;
-    get(id: string): Resource<Order> | null;
+    get(id: string): Resource<OrderAnswer> | null;
     subscriptions: {
         list(query?: PageQuery): Resource<SubscriptionPage> | null;
-        get(id: string): Resource<Subscription> | null;
+        get(id: string): Resource<SubscriptionAnswer> | null;
+    };
+}
+export interface Orders {
+    /** A page of the customer's orders: `{ orders, pagination }`. */
+    list(query?: PageQuery): Promise<OrderPage>;
+    /** One order: `{ order }`. */
+    get(id: string): Promise<OrderAnswer>;
+    subscriptions: {
+        /** A page of the customer's subscriptions: `{ subscriptions, pagination }`. */
+        list(query?: PageQuery): Promise<SubscriptionPage>;
+        /** One subscription: `{ subscription }`. */
+        get(id: string): Promise<SubscriptionAnswer>;
     };
+    resource: OrdersResources;
     /** Forgets what was kept of orders and subscriptions, so the next question is asked again. */
     refresh(): void;
 }

package/dist/orders/orders.js

@@ -1,14 +1,24 @@
+import { loadForCustomer } from '../customer-resources.js';
 export function createOrders(options) {
     const { api, customer } = options;
     // Nothing asked and an empty ask are the same question
     const asked = (q) => q ?? {};
-    return {
+    const resource = {
         list: (query) => customer.resource('orders.list', undefined, asked(query), (o) => api.list(query, o)),
         get: (id) => customer.resource('orders.get', id, undefined, (o) => api.get(id, o)),
         subscriptions: {
             list: (query) => customer.resource('subscriptions.list', undefined, asked(query), (o) => api.listSubscriptions(query, o)),
             get: (id) => customer.resource('subscriptions.get', id, undefined, (o) => api.getSubscription(id, o)),
         },
+    };
+    return {
+        list: (query) => loadForCustomer(resource.list(query)),
+        get: (id) => loadForCustomer(resource.get(id)),
+        subscriptions: {
+            list: (query) => loadForCustomer(resource.subscriptions.list(query)),
+            get: (id) => loadForCustomer(resource.subscriptions.get(id)),
+        },
+        resource,
         refresh() {
             for (const call of ['orders.list', 'orders.get', 'subscriptions.list', 'subscriptions.get'])
                 customer.forget(call);

package/dist/orders/types.d.ts

@@ -13,6 +13,7 @@ export interface PageInfo {
     total: number;
     totalPages: number;
 }
+/** How the store wraps a page of a list (`{ data, pagination }`): read as it is, and named where it comes in (`opened`, answer.ts). What the package gives back is `OrderPage`, `ReturnRequestPage`… */
 export interface Page<T> {
     data: T[];
     pagination: PageInfo;
@@ -83,6 +84,22 @@ export interface Subscription {
     /** The order the subscription came from. */
     order: Order | null;
 }
-export type OrderPage = Page<Order>;
-export type SubscriptionPage = Page<Subscription>;
+/** A page of the customer's orders. */
+export interface OrderPage {
+    orders: Order[];
+    pagination: PageInfo;
+}
+/** One order. */
+export interface OrderAnswer {
+    order: Order;
+}
+/** A page of the customer's subscriptions. */
+export interface SubscriptionPage {
+    subscriptions: Subscription[];
+    pagination: PageInfo;
+}
+/** One subscription. */
+export interface SubscriptionAnswer {
+    subscription: Subscription;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/returns/api.d.ts

@@ -1,27 +1,27 @@
 import type { HttpClient } from '../http.js';
 import type { CallOptions } from '../catalog/types.js';
 import type { AccessTokenOptions } from '../auth/api.js';
-import type { CreateGuestReturnInput, CreateReturnInput, GuestReturnSession, GuestVerifyAnswer, GuestVerifyInput, PageQuery, ReturnRequest, ReturnRequestPage } from './types.js';
+import type { CreateGuestReturnInput, CreateReturnInput, GuestReturnSessionAnswer, GuestVerifyAnswer, GuestVerifyInput, PageQuery, ReturnRequestAnswer, ReturnRequestPage } from './types.js';
 export interface ReturnApi {
     /** `GET /store-customer-return-requests` (JWT): the customer's requests, a page at a time. */
     list(input?: PageQuery, options?: CallOptions & AccessTokenOptions): Promise<ReturnRequestPage>;
     /** `GET /store-customer-return-requests/:id` (JWT). */
-    get(id: string, options?: CallOptions & AccessTokenOptions): Promise<ReturnRequest>;
+    get(id: string, options?: CallOptions & AccessTokenOptions): Promise<ReturnRequestAnswer>;
     /** `POST /store-customer-return-requests` (JWT): asks to return some of the items of an order (`201`). The store emails the customer (and the shop). */
-    create(input: CreateReturnInput, options?: CallOptions & AccessTokenOptions): Promise<ReturnRequest>;
+    create(input: CreateReturnInput, options?: CallOptions & AccessTokenOptions): Promise<ReturnRequestAnswer>;
     /** `DELETE /store-customer-return-requests/:id` (JWT): cancels a request that is still `pending` (400 for any other); gives back the one it cancelled. */
-    cancel(id: string, options?: CallOptions & AccessTokenOptions): Promise<ReturnRequest>;
+    cancel(id: string, options?: CallOptions & AccessTokenOptions): Promise<ReturnRequestAnswer>;
     /**
      * `POST …/guest/verify` (no JWT): asks the store to email a link to the address of the order, for a guest. It answers the same whether the order exists or not. An order that belongs to an account is refused
      * (400): its customer has to log in.
      */
     verifyGuest(input: GuestVerifyInput, options?: CallOptions): Promise<GuestVerifyAnswer>;
     /** `GET …/guest/session?token=` (no JWT): the order the link's token opens. 401 for a token that is not good or has ended. */
-    guestSession(token: string, options?: CallOptions): Promise<GuestReturnSession>;
+    guestSession(token: string, options?: CallOptions): Promise<GuestReturnSessionAnswer>;
     /** `POST …/guest` (no JWT, the token in the body): a guest asks to return some of the items of their order (`201`). */
-    createGuest(input: CreateGuestReturnInput, options?: CallOptions): Promise<ReturnRequest>;
+    createGuest(input: CreateGuestReturnInput, options?: CallOptions): Promise<ReturnRequestAnswer>;
     /** `DELETE …/guest/:id?token=` (no JWT): cancels a guest's request that is still `pending`. */
-    cancelGuest(id: string, token: string, options?: CallOptions): Promise<ReturnRequest>;
+    cancelGuest(id: string, token: string, options?: CallOptions): Promise<ReturnRequestAnswer>;
 }
 export declare function createReturnApi(http: HttpClient): ReturnApi;
 //# sourceMappingURL=api.d.ts.map

package/dist/returns/api.js

@@ -1,19 +1,21 @@
-// The calls of commerce-core that are about returns (`/store-customer-return-requests`), each asking one thing and giving back what the store answers, unchanged. A customer's need their JWT. A guest's need none: what proves
-// who they are is a TOKEN, in the link the store emailed to the address of the order (`guest/verify` asks for the email; the site's page `/returns?token=…` is where the link leads, and reads the token from the address).
+import { entity, opened } from '../answer.js';
+// The calls of commerce-core that are about returns (`/store-customer-return-requests`), each asking one thing and giving back what the store answers, named (`{ returnRequests, pagination }`, `{ returnRequest }`: the store sends a page
+// as `{ data, pagination }` and a request bare: opened here, once). A customer's need their JWT. A guest's need none: what proves who they are is a TOKEN, in the link the store emailed to the address of the order (`guest/verify`
+// asks for the email; the site's page `/returns?token=…` is where the link leads, and reads the token from the address).
 const PATH = '/store-customer-return-requests';
 const bearer = (options) => (options?.accessToken ? { Authorization: `Bearer ${options.accessToken}` } : {});
 const part = (id) => encodeURIComponent(id);
 const query = (q) => ({ page: q?.page, limit: q?.limit, sortBy: q?.sortBy, sortDirection: q?.sortDirection, lang: q?.lang });
 export function createReturnApi(http) {
     return {
-        list: (input, options) => http.request({ path: PATH, query: query(input), headers: bearer(options), signal: options?.signal }),
-        get: (id, options) => http.request({ path: `${PATH}/${part(id)}`, headers: bearer(options), signal: options?.signal }),
-        create: (input, options) => http.request({ method: 'POST', path: PATH, body: input, headers: bearer(options), signal: options?.signal }),
-        cancel: (id, options) => http.request({ method: 'DELETE', path: `${PATH}/${part(id)}`, headers: bearer(options), signal: options?.signal }),
+        list: async (input, options) => opened('returnRequests', await http.request({ path: PATH, query: query(input), headers: bearer(options), signal: options?.signal })),
+        get: async (id, options) => entity('returnRequest', await http.request({ path: `${PATH}/${part(id)}`, headers: bearer(options), signal: options?.signal })),
+        create: async (input, options) => entity('returnRequest', await http.request({ method: 'POST', path: PATH, body: input, headers: bearer(options), signal: options?.signal })),
+        cancel: async (id, options) => entity('returnRequest', await http.request({ method: 'DELETE', path: `${PATH}/${part(id)}`, headers: bearer(options), signal: options?.signal })),
         verifyGuest: (input, options) => http.request({ method: 'POST', path: `${PATH}/guest/verify`, body: input, signal: options?.signal }),
-        guestSession: (token, options) => http.request({ path: `${PATH}/guest/session`, query: { token }, signal: options?.signal }),
-        createGuest: (input, options) => http.request({ method: 'POST', path: `${PATH}/guest`, body: input, signal: options?.signal }),
-        cancelGuest: (id, token, options) => http.request({ method: 'DELETE', path: `${PATH}/guest/${part(id)}`, query: { token }, signal: options?.signal }),
+        guestSession: async (token, options) => entity('returnSession', await http.request({ path: `${PATH}/guest/session`, query: { token }, signal: options?.signal })),
+        createGuest: async (input, options) => entity('returnRequest', await http.request({ method: 'POST', path: `${PATH}/guest`, body: input, signal: options?.signal })),
+        cancelGuest: async (id, token, options) => entity('returnRequest', await http.request({ method: 'DELETE', path: `${PATH}/guest/${part(id)}`, query: { token }, signal: options?.signal })),
     };
 }
 //# sourceMappingURL=api.js.map

package/dist/returns/index.d.ts

@@ -1,6 +1,6 @@
 export { createReturnApi } from './api.js';
 export type { ReturnApi } from './api.js';
 export { createReturns } from './returns.js';
-export type { Returns } from './returns.js';
-export type { CreateGuestReturnInput, CreateReturnInput, GuestOrderItem, GuestReturnSession, GuestVerifyAnswer, GuestVerifyInput, ReturnItem, ReturnItemInput, ReturnRequest, ReturnRequestPage, ReturnStatus, } from './types.js';
+export type { Returns, ReturnsResources } from './returns.js';
+export type { CreateGuestReturnInput, CreateReturnInput, GuestOrderItem, GuestReturnSession, GuestReturnSessionAnswer, GuestVerifyAnswer, GuestVerifyInput, ReturnItem, ReturnItemInput, ReturnRequest, ReturnRequestAnswer, ReturnRequestPage, ReturnStatus, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/returns/returns.d.ts

@@ -1,23 +1,34 @@
-import type { CustomerResources } from '../customer-resources.js';
+import { type CustomerResources } from '../customer-resources.js';
 import type { Cache } from '../cache.js';
 import { type Resource, type ResourceIdentity } from '../resource.js';
 import type { ReturnApi } from './api.js';
-import type { CreateGuestReturnInput, CreateReturnInput, GuestReturnSession, GuestVerifyAnswer, GuestVerifyInput, PageQuery, ReturnRequest, ReturnRequestPage } from './types.js';
-export interface Returns {
+import type { CreateGuestReturnInput, CreateReturnInput, GuestReturnSessionAnswer, GuestVerifyAnswer, GuestVerifyInput, PageQuery, ReturnRequestAnswer, ReturnRequestPage } from './types.js';
+export interface ReturnsResources {
     list(query?: PageQuery): Resource<ReturnRequestPage> | null;
-    get(id: string): Resource<ReturnRequest> | null;
-    /** Asks to return some of the items of an order. Throws what the store refuses (an order that is not the customer's: 404). */
-    create(input: CreateReturnInput): Promise<ReturnRequest>;
-    /** Cancels a request that is still pending (the store refuses any other: 400). */
-    cancel(id: string): Promise<ReturnRequest>;
+    get(id: string): Resource<ReturnRequestAnswer> | null;
+    guest: {
+        /** The order the link's token opens: a resource, so a page shows it (and what is asked of the same token is asked once). */
+        session(token: string): Resource<GuestReturnSessionAnswer>;
+    };
+}
+export interface Returns {
+    /** A page of the customer's return requests: `{ returnRequests, pagination }`. */
+    list(query?: PageQuery): Promise<ReturnRequestPage>;
+    /** One request: `{ returnRequest }`. */
+    get(id: string): Promise<ReturnRequestAnswer>;
+    /** Asks to return some of the items of an order: `{ returnRequest }`. Throws what the store refuses (an order that is not the customer's: 404). */
+    create(input: CreateReturnInput): Promise<ReturnRequestAnswer>;
+    /** Cancels a request that is still pending (the store refuses any other: 400): `{ returnRequest }`. */
+    cancel(id: string): Promise<ReturnRequestAnswer>;
     guest: {
         /** Asks the store to email the link (it answers the same whether the order exists or not). */
         requestLink(input: GuestVerifyInput): Promise<GuestVerifyAnswer>;
-        /** The order the link's token opens: a resource, so a page shows it (and what is asked of the same token is asked once). */
-        session(token: string): Resource<GuestReturnSession>;
-        create(input: CreateGuestReturnInput): Promise<ReturnRequest>;
-        cancel(id: string, token: string): Promise<ReturnRequest>;
+        /** The order the link's token opens: `{ returnSession }`. */
+        session(token: string): Promise<GuestReturnSessionAnswer>;
+        create(input: CreateGuestReturnInput): Promise<ReturnRequestAnswer>;
+        cancel(id: string, token: string): Promise<ReturnRequestAnswer>;
     };
+    resource: ReturnsResources;
     /** Forgets what was kept of the customer's requests, so the next question is asked again. */
     refresh(): void;
 }

package/dist/returns/returns.js

@@ -1,11 +1,17 @@
+import { loadForCustomer } from '../customer-resources.js';
 import { createResourceFactory } from '../resource.js';
 export function createReturns(options) {
     const { api, customer } = options;
     const make = createResourceFactory(options.cache, options.identity);
     const forgetMine = () => { customer.forget('returns.list'); customer.forget('returns.get'); };
-    return {
+    const resource = {
         list: (query) => customer.resource('returns.list', undefined, query ?? {}, (o) => api.list(query, o)),
         get: (id) => customer.resource('returns.get', id, undefined, (o) => api.get(id, o)),
+        guest: { session: (token) => make('returns.guestSession', token, undefined, (o) => api.guestSession(token, o)) },
+    };
+    return {
+        list: (query) => loadForCustomer(resource.list(query)),
+        get: (id) => loadForCustomer(resource.get(id)),
         async create(input) {
             const made = await api.create(input);
             forgetMine();
@@ -21,10 +27,11 @@ export function createReturns(options) {
         },
         guest: {
             requestLink: (input) => api.verifyGuest(input),
-            session: (token) => make('returns.guestSession', token, undefined, (o) => api.guestSession(token, o)),
+            session: (token) => resource.guest.session(token).load(),
             create: (input) => api.createGuest(input),
             cancel: (id, token) => api.cancelGuest(id, token),
         },
+        resource,
         refresh: forgetMine,
     };
 }

package/dist/returns/types.d.ts

@@ -1,4 +1,4 @@
-import type { OrderAddress, Page, PageQuery } from '../orders/types.js';
+import type { OrderAddress, PageInfo, PageQuery } from '../orders/types.js';
 export type ReturnStatus = 'pending' | 'accepted' | 'rejected' | 'refunded';
 /** One item of a return: which item of the order (`orderItemId` of an `OrderItem`) and how many of it. */
 export interface ReturnItemInput {
@@ -53,7 +53,15 @@ export interface ReturnRequest {
     createdAt: string;
     updatedAt: string;
 }
-export type ReturnRequestPage = Page<ReturnRequest>;
+/** A page of the customer's return requests. */
+export interface ReturnRequestPage {
+    returnRequests: ReturnRequest[];
+    pagination: PageInfo;
+}
+/** One return request (what is asked, read or cancelled). */
+export interface ReturnRequestAnswer {
+    returnRequest: ReturnRequest;
+}
 export type { PageQuery };
 /** How a guest says which order: the address it was bought with, and the order's id OR its reference (the number the customer was given). */
 export interface GuestVerifyInput {
@@ -96,4 +104,8 @@ export interface GuestReturnSession {
         items: GuestOrderItem[];
     };
 }
+/** What a guest's link opens, named: `{ returnSession }`. */
+export interface GuestReturnSessionAnswer {
+    returnSession: GuestReturnSession;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/reviews/api.d.ts

@@ -3,8 +3,8 @@ import type { CallOptions } from '../catalog/types.js';
 import type { AccessTokenOptions } from '../auth/api.js';
 import type { MyReviewPage, MyReviewsQuery, ReviewAnswer, ReviewDeletedAnswer, ReviewInput, ReviewPatch } from './types.js';
 export interface ReviewApi {
-    /** `GET /reviews/by-customer`: the customer's own reviews, a page at a time. */
-    mine(input?: MyReviewsQuery, options?: CallOptions & AccessTokenOptions): Promise<MyReviewPage>;
+    /** `GET /reviews/by-customer`: the customer's own reviews, a page at a time: `{ reviews, pagination }` (the store sends the list as `data`). */
+    list(input?: MyReviewsQuery, options?: CallOptions & AccessTokenOptions): Promise<MyReviewPage>;
     /**
      * `POST /reviews/product-variants/:variantId`: writes the customer's review of a variant (`201`). Refused with `EMAIL_NOT_VERIFIED` (400: the address is not verified), `REVIEW_ALREADY_EXISTS` (409) and 404
      * for a variant that is not the store's.

package/dist/reviews/api.js

@@ -1,12 +1,13 @@
+import { opened } from '../answer.js';
 // The calls of commerce-core that are about what a customer writes of what they bought (`/reviews`), each asking one thing and giving back what the store answers, unchanged (what it writes or removes comes in `data`).
 // All need the JWT of the customer; a store can turn reviews off (403 "Reviews are disabled for this store"). Reading everybody's reviews of a product is the catalog's.
 const bearer = (options) => (options?.accessToken ? { Authorization: `Bearer ${options.accessToken}` } : {});
 const part = (id) => encodeURIComponent(id);
 export function createReviewApi(http) {
     return {
-        mine: (input, options) => http.request({
+        list: async (input, options) => opened('reviews', await http.request({
             path: '/reviews/by-customer', query: { page: input?.page, limit: input?.limit, sortBy: input?.sortBy, sortDirection: input?.sortDirection, rating: input?.rating, lang: input?.lang }, headers: bearer(options), signal: options?.signal,
-        }),
+        })),
         create: (variantId, input, options) => http.request({ method: 'POST', path: `/reviews/product-variants/${part(variantId)}`, body: input, headers: bearer(options), signal: options?.signal }),
         update: (id, patch, options) => http.request({ method: 'PATCH', path: `/reviews/${part(id)}`, body: patch, headers: bearer(options), signal: options?.signal }),
         remove: (id, options) => http.request({ method: 'DELETE', path: `/reviews/${part(id)}`, headers: bearer(options), signal: options?.signal }),

package/dist/reviews/index.d.ts

@@ -1,9 +1,9 @@
 export { createReviewApi } from './api.js';
 export type { ReviewApi } from './api.js';
 export { createReviews } from './reviews.js';
-export type { Reviews } from './reviews.js';
+export type { Reviews, ReviewsResources } from './reviews.js';
 export { reviewAbility } from './rules.js';
 export type { ReviewAbility } from './rules.js';
 export { REVIEW_ERROR_CODES } from './types.js';
-export type { MyReview, MyReviewPage, MyReviewsQuery, CustomerReview, ReviewAnswer, ReviewDeletedAnswer, ReviewInput, ReviewPatch } from './types.js';
+export type { MyReview, MyReviewPage, MyReviewsQuery, CustomerReview, ReviewAnswer, ReviewDeletedAnswer, ReviewInput, ReviewPatch, ReviewResult } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/reviews/reviews.d.ts

@@ -1,18 +1,24 @@
 import type { AuthStore } from '../auth/store.js';
 import type { CachedCatalog } from '../catalog/cached.js';
-import type { CustomerResources } from '../customer-resources.js';
+import { type CustomerResources } from '../customer-resources.js';
 import type { Resource } from '../resource.js';
 import type { ReviewApi } from './api.js';
-import { type MyReviewPage, type MyReviewsQuery, type CustomerReview, type ReviewInput, type ReviewPatch } from './types.js';
+import { type MyReviewPage, type MyReviewsQuery, type ReviewInput, type ReviewPatch, type ReviewResult } from './types.js';
+export interface ReviewsResources {
+    list(query?: MyReviewsQuery): Resource<MyReviewPage> | null;
+}
 export interface Reviews {
-    mine(query?: MyReviewsQuery): Resource<MyReviewPage> | null;
-    /** Writes the customer's review of a variant. Throws what the store refuses (`EMAIL_NOT_VERIFIED`, `REVIEW_ALREADY_EXISTS`, a variant that is not the store's) and, for a guest, `LOGIN_REQUIRED`. */
-    create(variantId: string, input: ReviewInput): Promise<CustomerReview>;
-    update(id: string, patch: ReviewPatch): Promise<CustomerReview>;
+    /** A page of the customer's own reviews: `{ reviews, pagination }`. */
+    list(query?: MyReviewsQuery): Promise<MyReviewPage>;
+    /** Writes the customer's review of a variant: `{ review }`. Throws what the store refuses (`EMAIL_NOT_VERIFIED`, `REVIEW_ALREADY_EXISTS`, a variant that is not the store's) and, for a guest, `LOGIN_REQUIRED`. */
+    create(variantId: string, input: ReviewInput): Promise<ReviewResult>;
+    /** Changes what is given of the customer's own review: `{ review }`. */
+    update(id: string, patch: ReviewPatch): Promise<ReviewResult>;
     /** Removes the customer's own review; says which. */
     remove(id: string): Promise<{
         id: string;
     }>;
+    resource: ReviewsResources;
 }
 export declare function createReviews(options: {
     api: ReviewApi;

package/dist/reviews/reviews.js

@@ -1,3 +1,4 @@
+import { loadForCustomer } from '../customer-resources.js';
 import { CommerceError } from '../errors.js';
 import { REVIEW_ERROR_CODES } from './types.js';
 export function createReviews(options) {
@@ -6,24 +7,27 @@ export function createReviews(options) {
     const login = () => new CommerceError({ kind: 'http', status: 401, code: REVIEW_ERROR_CODES.loginRequired, message: 'Log in to write a review.' });
     /** What was kept that a review changes: the customer's own, and the catalog's reviews of its product (all of them when the product is not known). */
     const forget = (productId) => {
-        customer.forget('reviews.mine');
+        customer.forget('reviews.list');
         catalog.invalidate(productId ? { call: 'products.getReviews', subject: productId } : { call: 'products.getReviews' });
     };
+    const resource = {
+        list: (query) => customer.resource('reviews.list', undefined, query ?? {}, (o) => api.list(query, o)),
+    };
     return {
-        mine: (query) => customer.resource('reviews.mine', undefined, query ?? {}, (o) => api.mine(query, o)),
+        list: (query) => loadForCustomer(resource.list(query)),
         async create(variantId, input) {
             if (!loggedIn())
                 throw login();
             const { data } = await api.create(variantId, input);
             forget(data.productId);
-            return data;
+            return { review: data };
         },
         async update(id, patch) {
             if (!loggedIn())
                 throw login();
             const { data } = await api.update(id, patch);
             forget(data.productId);
-            return data;
+            return { review: data };
         },
         async remove(id) {
             if (!loggedIn())
@@ -32,6 +36,7 @@ export function createReviews(options) {
             forget();
             return data;
         },
+        resource,
     };
 }
 //# sourceMappingURL=reviews.js.map

package/dist/reviews/types.d.ts

@@ -1,4 +1,4 @@
-import type { Page, PageQuery } from '../orders/types.js';
+import type { PageInfo, PageQuery } from '../orders/types.js';
 export interface ReviewInput {
     rating: number;
     title: string;
@@ -31,11 +31,19 @@ export interface MyReviewsQuery extends PageQuery {
     /** Only the reviews with this rating (1 to 5). */
     rating?: number;
 }
-export type MyReviewPage = Page<MyReview>;
-/** What the store answers to writing a review: the review, in `data`. */
+/** A page of the customer's own reviews. */
+export interface MyReviewPage {
+    reviews: MyReview[];
+    pagination: PageInfo;
+}
+/** What the store answers to writing a review, as it sends it: the review, in `data` (the package gives it as `ReviewResult`). */
 export interface ReviewAnswer {
     data: CustomerReview;
 }
+/** What writing or changing a review gives back: the review, by name. */
+export interface ReviewResult {
+    review: CustomerReview;
+}
 /** What it answers to removing one: the review that was removed (its `id` at least; the store sends the whole row). */
 export interface ReviewDeletedAnswer {
     data: {

package/dist/wishlist/wishlist.d.ts

@@ -6,7 +6,8 @@ import { type WishlistItem } from './types.js';
 export interface WishlistState {
     /** Whose wishlist this is. `unknown` until it is known whether a customer is logged in; a guest's is empty. */
     owner: Owner;
-    items: WishlistItem[];
+    /** The wishlist: what the customer has put in it. */
+    wishlist: WishlistItem[];
     /** The variants that are in it: what a heart on a product asks. */
     variantIds: string[];
     count: number;

package/dist/wishlist/wishlist.js

@@ -6,7 +6,7 @@ const idsOf = (items) => items.flatMap((i) => i.product.variants.map((v) => v.id
 const isDisabled = (error) => error.status === 403 && (error.code === WISHLIST_ERROR_CODES.disabled || /disabled/i.test(error.message));
 export function createWishlist(options) {
     const { api, auth } = options;
-    const holder = createStateHolder({ owner: 'unknown', items: [], variantIds: [], count: 0, loaded: false, enabled: null, busy: false, error: null });
+    const holder = createStateHolder({ owner: 'unknown', wishlist: [], variantIds: [], count: 0, loaded: false, enabled: null, busy: false, error: null });
     const set = holder.set;
     const queue = createSerialQueue((busy) => set({ busy }));
     // Counts the times the wishlist changed hands: an answer that comes after that is about a wishlist that is not this one any more
@@ -17,22 +17,22 @@ export function createWishlist(options) {
             const list = await api.list();
             if (epoch !== mine)
                 return;
-            set({ items: list.data, variantIds: idsOf(list.data), count: list.data.length, loaded: true, enabled: true, error: null });
+            set({ wishlist: list.data, variantIds: idsOf(list.data), count: list.data.length, loaded: true, enabled: true, error: null });
         }
         catch (error) {
             if (epoch !== mine)
                 return;
             const failure = toCommerceError(error);
-            set(isDisabled(failure) ? { items: [], variantIds: [], count: 0, loaded: true, enabled: false, error: null } : { error: failure });
+            set(isDisabled(failure) ? { wishlist: [], variantIds: [], count: 0, loaded: true, enabled: false, error: null } : { error: failure });
         }
     }
     function toGuest() {
         epoch++;
-        set({ owner: 'guest', items: [], variantIds: [], count: 0, loaded: true, error: null });
+        set({ owner: 'guest', wishlist: [], variantIds: [], count: 0, loaded: true, error: null });
     }
     function toCustomer() {
         epoch++;
-        set({ owner: 'customer', items: [], variantIds: [], count: 0, loaded: false, error: null });
+        set({ owner: 'customer', wishlist: [], variantIds: [], count: 0, loaded: false, error: null });
         void queue.run(loadCustomer);
     }
     const following = followAuth(auth, { current: () => holder.get().owner, toGuest, toCustomer });

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@webround/commerce",
-    "version": "0.4.0",
+    "version": "0.4.1",
     "type": "module",
     "main": "./dist/index.js",
     "module": "./dist/index.js",