@asstio-dev/storefront 0.32.0 → 0.40.0-market.1

package/README.md

@@ -15,7 +15,7 @@ served publicly at <https://api.storefront.asstio.com/docs/onboarding>. This fil
 package.
 
 ```ts
-import { createStorefrontClient, filterQuery } from "@asstio-dev/storefront";
+import { createStorefrontClient, filterQuery, requireBinding } from "@asstio-dev/storefront";
 
 // Your key: process.env.STOREFRONT_SITE_KEY on a server, import.meta.env.VITE_… in a bundler.
 declare const STOREFRONT_SITE_KEY: string;
@@ -24,7 +24,8 @@ const storefront = createStorefrontClient({
   baseUrl: "https://api.storefront.asstio.com",
   siteKey: STOREFRONT_SITE_KEY, // publishable in the browser, secret only on the server
   market: "se",
-  acceptLanguage: "sv-SE",
+  country: "SE",
+  locale: "sv",
 });
 
 const { data, error } = await storefront.GET("/v1/products", {
@@ -43,6 +44,18 @@ if (error) throw new Error(`${error.code}: ${error.detail ?? ""}`);
 console.log(data.total, data.items, data.warnings);
 ```
 
+A client's context is fixed when it is built, so a site with several contexts has one client per context. Leave out what the
+API may resolve (see [Headers](#headers)), or pass a page binding from `GET /v1/site` instead of the three values:
+
+```ts
+const { data: siteInfo } = await storefront.GET("/v1/site", {});
+const germanInSwedish = createStorefrontClient({
+  baseUrl: "https://api.storefront.asstio.com",
+  siteKey: STOREFRONT_SITE_KEY,
+  binding: requireBinding(siteInfo!, "eur/DE/sv"),   // sends X-Market: eur, X-Country: DE, X-Locale: sv
+});
+```
+
 ```ts
 // A product with many variants comes back with variants: null and a variantCount; page them:
 const { data: page } = await storefront.GET("/v1/products/{slugOrId}/variants", {
@@ -191,6 +204,30 @@ const { data: listing } = await storefront.GET("/v1/products", {
 });
 ```
 
+### Prices and buying
+
+Every card, product and variant carries an `offer`. Render it with three helpers instead of reading its fields:
+
+```ts
+import { displayPrice, isBuyable, type OfferDto } from "@asstio-dev/storefront";
+
+export function buyBox(offer: OfferDto) {
+  // The offer's displayBasis side of its pair: ex for a dealer, inc for a consumer. Null means "show no price", never 0.
+  const price = displayPrice(offer);        // { amount: "100.00", basis: "ex", currency: "SEK" }
+  return {
+    label: price ? `${price.amount} ${price.currency} ${price.basis === "ex" ? "excl. VAT" : "incl. VAT"}` : null,
+    canBuy: isBuyable(offer),
+  };
+}
+```
+
+- `displayPrice` is null when `offerStatus` is not `available` (render `loginRequired` as "Sign in for prices"), and when
+  the pair lacks the side to show. It never falls back to the other side or computes an amount. `isPriceVisible(offer)` is
+  whether it has an amount.
+- `isBuyable` is `offerStatus` and `purchaseStatus` both `available`. `purchaseStatus` already folds in permission,
+  freshness, sellability and a complete price, so a partial price can be visible and still not buyable. Never decide it
+  from `stock`: the API sends no public stock quantity, and zero stock is buyable on a backorder site.
+
 ### Variant links
 
 A link to one variant is the product URL plus `?variant={variantId}` (the id from `variants[].id`); `variant.url` is
@@ -207,7 +244,7 @@ if (product?.redirectTo) permanentRedirect(redirectTarget(product.url!, raw));
 // product.selectedVariantStatus: null (absent: your default), "matched" (preselect product.selectedVariant),
 // "notSoldHere" (show it as unavailable here, preselect nothing), "unknown" (note that it is gone, preselect nothing).
 if (!product) notFound();
-const ld = productJsonLd(product, { site, market: "se" });
+const ld = productJsonLd(product, { site, binding: "se/SE/sv" });
 ```
 
 Pass the **raw search string** to `readVariantParam` and `redirectTarget` when you can (for example from a
@@ -221,7 +258,7 @@ Pure helpers that compute schema.org JSON-LD and `<head>` data from the DTOs. Th
 writes the markup. No backend call, no DOM, no dependency.
 
 **Product JSON-LD.** `productJsonLd` returns a `Product` (one variant) or a `ProductGroup` with one `Product` and
-`Offer` per variant sold on the market. Each variant's link is `v.url` from the API (see Variant links above), so no
+`Offer` per variant sold in the page's context. Each variant's link is `v.url` from the API (see Variant links above), so no
 `variantUrl` hook is needed; pass one only to override it. Google needs a distinct URL per variant, and opening that
 URL **must preselect the variant** on your page. `productJsonLd` reads `product.selectedVariant` itself.
 `variesBy` maps your option names to `size`, `color`, `material` or `pattern`; unmapped options still name the
@@ -230,7 +267,7 @@ variants. A product with more than 100 variants arrives with `variants: null`: p
 
 ```tsx
 const ld = productJsonLd(product, {
-  site, market: "se",
+  site, binding: "se/SE/sv",   // the site.bindings id the page was requested on
   variesBy: { Storlek: "size", Färg: "color" },
 });
 <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: jsonLdScript(ld) }} />
@@ -248,21 +285,25 @@ const crumbs = breadcrumbJsonLd(r.breadcrumb, { home: { name: "Hem", url: "https
 
 **Head.** `productHead`, `collectionHead` (takes your own `description`; the API has none for collections) and
 `brandHead` return a framework-neutral `SeoHead`: title, description (cut at 160 characters on a word boundary),
-canonical, hreflang alternates (keyed `language-COUNTRY`, `x-default` from the site's default market; override with
-`xDefault: "<market>"` or `false`), and Open Graph / Twitter meta. `titleTemplate: "%s | Moory"` applies to `<title>`
-only, never to the social titles. In Next.js:
+canonical (the page's own URL on its binding, base path and prefix included), `robots: "noindex,follow"` on a secondary
+(non-indexable) binding, hreflang alternates (the API's `alternates`: the indexable bindings where the page exists
+publicly, `x-default` from the site's default binding; override with `xDefault: "<binding id>"` or `false`; none on a
+secondary binding), and Open Graph / Twitter meta. `binding` is the `site.bindings` id the page was requested on
+(its `X-Market`, `X-Country` and `X-Locale`). `titleTemplate: "%s | Moory"` applies to `<title>` only, never to the
+social titles. In Next.js:
 
 ```ts
 export async function generateMetadata(): Promise<Metadata> {
-  return toNextMetadata(productHead(product, { site, market: "se", titleTemplate: "%s | Moory" }));
+  return toNextMetadata(productHead(product, { site, binding: "se/SE/sv", titleTemplate: "%s | Moory" }));
 }
 ```
 
 Titles come out as `{ absolute }` on purpose, so a layout's `title.template` does not apply a second time.
 
-**Sitemap.** `sitemapEntries` reads every sitemap URL of one market: `GET /v1/site` once, then for each type
-(`product`, `collection`, `brand`; default all three) a cursor walk of `GET /v1/sitemap` from `cursor=start` along
-`nextCursor`, with no 10 000-row ceiling. `toNextSitemap` turns the result into Next.js's `app/sitemap.ts` shape:
+**Sitemap.** `sitemapEntries` reads every sitemap URL of one binding: `GET /v1/site`, then for each type
+(`product`, `collection`, `brand`; default all three) a cursor walk of `GET /v1/sitemap?binding=` from `cursor=start` along
+`nextCursor`, with no 10 000-row ceiling. `since` (optional) limits it to entries changed at or after a timestamp. A secondary
+(non-indexable) binding has an empty sitemap. `toNextSitemap` turns the result into Next.js's `app/sitemap.ts` shape:
 
 ```ts
 import type { MetadataRoute } from "next";
@@ -270,32 +311,42 @@ import type { MetadataRoute } from "next";
 export const dynamic = "force-dynamic";
 
 export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
-  const market = process.env.STOREFRONT_MARKET!;            // the same market the client sends as X-Market
-  const api = createStorefrontClient({ baseUrl: API_URL, siteKey: SITE_KEY, market });
-  const result = await sitemapEntries(api, { market });
-  if (!result.complete) console.warn("Sitemap: Storefront API unavailable; serving a partial sitemap.");
+  const binding = process.env.STOREFRONT_BINDING!;          // a site.bindings id, e.g. "se/SE/sv": one sitemap per binding
+  const api = createStorefrontClient({ baseUrl: API_URL, siteKey: SITE_KEY });
+  const result = await sitemapEntries(api, { binding });
+  if (!result.complete) console.warn("Sitemap: incomplete walk");
   return toNextSitemap(result);
 }
 ```
 
-- `market` is required and must be the client's market. It is matched case-insensitively against the site's markets;
-  an unknown one throws `SeoError` before any page is read. Never pass the site's default instead of the request's.
-- hreflang tags are `language-COUNTRY` (`sv-SE`, never the market code `se`), each entry lists itself, and `x-default`
-  appears only when the site's default market has the page. Two markets with the same tag and different URLs drop that
-  entry's alternates; the URL stays listed.
+- `binding` is required and must be one of `site.bindings`; an unknown one throws `SeoError` before any page is read.
+- hreflang tags are the bindings' compiled tags (`sv-SE`, `en-DE` for `en-GB` shipped to Germany; never the market code
+  `se`), each entry lists itself when its binding is indexable, and `x-default` appears only when the site's default
+  binding has the page. Two bindings with the same tag and different URLs drop that entry's alternates; the URL stays
+  listed.
 - `lastModified` is left out when the API reports the Unix epoch (collections carry no timestamp of their own).
-- `complete: false`: a transport failure, a 5xx, `INDEX_UNAVAILABLE` or `SITE_REGISTRY_WARMING` stopped the walk; the
-  entries read so far are returned. Any other problem (a 400 such as `INVALID_CURSOR`) throws.
+- A walk restarts once, whole: on `409 CURSOR_EXPIRED` (a publish retired the generation, or a cursor is over an hour old),
+  and when its responses name more than one `X-Config-Version` (a publish between two types). The new walk's entries
+  replace the old ones. If a publish removed the binding, the restart throws `SeoError`.
+- `complete: true`: every type's walk finished on its own catalog generation, and the config version did not change
+  between types. It does not promise one generation for the whole result: the API names no generation in a response, so a
+  rebuild at the same config version between two types is not detected. That is acceptable for a sitemap, because two
+  generations at one config version carry the same URL model and the next render reads the newer one.
+- `complete: false`: a transport failure, a 5xx, `INDEX_UNAVAILABLE` or `SITE_REGISTRY_WARMING` stopped the walk, or the
+  restart could not meet that promise either. `entries` is what the last walk read, so a restart that stopped early can
+  hold less than the first walk did. Only a first walk that finished replaces such a restart, which gives every entry when
+  a config version change was the only trouble. Any other problem throws, a 400 such as `INVALID_CURSOR` included. A preview
+  key can meet that one when its draft is created or published mid-walk: run the walk again.
 - An API older than cursor paging throws "the Storefront API does not support sitemap cursors; deploy the API first"
   rather than ending the walk after one page.
 - A walk is an eventually consistent crawl, not a snapshot: a product added mid-walk may wait for the next render.
 
 **Errors.** `SeoError` means a caller or configuration error: `redirectTo` is set (answer 301 instead), an unknown
-market, a bad `variesBy` value, a variant URL (`v.url` or the optional `variantUrl` hook) that is missing, not an absolute http(s) URL or repeated for two variants, or
-two markets with the same `language-COUNTRY` and different URLs. Catch it at your SEO boundary and fix the market
-config. Holes in the data never throw: a missing image, description or price only leaves that part out.
+binding, a bad `variesBy` value, a variant URL (`v.url` or the optional `variantUrl` hook) that is missing, not an absolute http(s) URL or repeated for two variants, or
+two bindings with the same hreflang and different URLs. Catch it at your SEO boundary and fix the site's
+bindings. Holes in the data never throw: a missing image, description or price only leaves that part out.
 
-hreflang sets are only as reciprocal as the API's `alternateUrls`; the SDK renders what the API gives.
+hreflang sets are only as reciprocal as the API's `alternates`; the SDK renders what the API gives.
 
 ### Search events
 
@@ -360,8 +411,11 @@ know nothing about consent or a data layer.
 | order line (product) | the line `sku` | the variant's brand | the unit price | the line's | options |
 
 - A card is a family impression; later events carry the purchased sku. Pass `itemId` to report at family level.
+- Cards, variants and cart lines read the API's price pair: `ex` by default, `inc` with `tax: "include"`, never computed
+  and in the currency's own precision (three decimals in KWD, none in JPY). A partial price without that side throws
+  `AnalyticsError`. Checkout and order lines have no pair yet: they net `unitPriceInc` at `vatRate` and round to two decimals.
 - `price` and `value` are **net of VAT** by default, as GA4 defines them: 2 × 125.00 at 25 % gives `price: 100`,
-  `value: 200`. `value` is the sum of the items' rounded prices, so it need not match accounting to the öre (3 × 9.99 at
+  `value: 200`. `value` is the sum of the items' prices, so it need not match accounting to the öre (3 × 9.99 at
   25 % gives `price: 7.99`, `value: 23.97`). Pass `tax: "include"` to report gross on purpose.
 - For `add_to_cart` and `remove_from_cart`, pass `quantity`: the positive number of units added or removed, never the
   line's new total.
@@ -509,8 +563,9 @@ below), Walley `*.walleypay.com`, plus their `frame-src`/`script-src`/`connect-s
 integration guide lists the exact hosts.
 
 Problem codes you will meet here: `CART_EMPTY`, `CHECKOUT_CART_CHANGED` (with `cart`), `CHECKOUT_PREVIEW_KEY`,
-`CHECKOUT_MARKET_MISMATCH` (switch the cart's market first, then sync), `OPTION_NOT_AVAILABLE`,
-`ORIGIN_NOT_ALLOWED`, `CHECKOUT_UNAVAILABLE` and `CHECKOUT_PROVIDER_UNAVAILABLE` (503, `Retry-After`),
+`CONTEXT_MISMATCH` (409: the request's market or country is not the cart's, the cart is under `cart`; send the cart's, or
+move it with `POST /v1/cart/context`, then sync), `OPTION_NOT_AVAILABLE`,
+`ORIGIN_NOT_ALLOWED`, `CHECKOUT_UNAVAILABLE` (503, with `Retry-After` when it is worth retrying) and `CHECKOUT_PROVIDER_UNAVAILABLE` (503, `Retry-After`),
 `CHECKOUT_IN_PROGRESS` (409, `Retry-After`), `CHECKOUT_PROVIDER_REJECTED` (502), `CHECKOUT_NOT_FOUND`,
 `ORDER_NOT_FOUND`, `SITE_KEYS_SYNCING` (503 for a secret key on a freshly created site, `Retry-After`).
 
@@ -649,13 +704,21 @@ A link opened in another browser has no binding: the answer is `409 SIGN_IN_CONF
 `SIGN_IN_INVALID`: start a new sign-in. Redirect to the view's `returnPath` (or your default) yourself.
 
 **Sessions.** Build a client per request, never a module singleton: `shopperClient(config)` reads the session cookie
-(`createShopperClient({ baseUrl, serverKey, market, session, shopperIp })` outside Next.js). `getSession`, `getMe` and
+(`createShopperClient({ baseUrl, serverKey, session, shopperIp, binding })` outside Next.js). `AccountActionConfig` and
+`createShopperClient` take the same context as `createStorefrontClient`: `market`, `country` and `locale`, each optional, or
+a `binding`. `getSession`, `getMe` and
 `getMyCompany` read who is signed in; `switchPrincipalAction(config, principal)` acts as another principal (`"consumer"` or a
 membership id), rotates the session and points your cart cookie at the new principal's saved cart, or clears it when that
 principal has none; `signOutAction(config, { everywhere? })` clears the session, sign-in, cart and
 browser-cart cookies whatever the API answers. A session that no longer validates is `401 SESSION_INVALID` on **every**
 route, never a silent signed-out answer: render signed-out, and let the next action clear the cookie.
 
+**Private data at a session change.** A verify or switch that took effect, and every sign-out, returns
+`dropPrivateData: true`: the shopper is now someone else, so throw away what the browser still holds for the old one (a cart
+view, prices, account data) and read again. After a sign-in that includes the adopted cart: the guest's view of it goes. A
+switch keeps the rotated session and the cart cookie now names the new principal's own cart. A failed verify or switch
+changed nothing and has no such flag. On the server, never put priced private data in a shared cache or ISR.
+
 **Saved carts.** With a session, `POST /v1/cart` returns the principal's saved cart (or creates one) and `GET /v1/me/cart`
 reads it; the cart routes work on it with its token **and** the session. A saved cart's token without its owner's session —
 another device signed out, another principal, another account — is `404 NOT_FOUND`, exactly an unknown token; a principal
@@ -712,16 +775,39 @@ export async function beginSignedInCheckout(savedCart: string) {
 
 ## Headers
 
-Every call the client makes carries these; you never set them by hand.
+The client sets `X-Site-Key` and the context it was built with: `X-Market`, `X-Country` and `X-Locale`, from `market`,
+`country` and `locale` or from a `binding`. It leaves out what you leave out: the API then resolves it as below, and
+`POST /v1/cart` or `POST /v1/checkout` on a market with several countries answers `COUNTRY_REQUIRED`. The context cannot
+change after the client is built, and it wins over a header passed on a call: another context is another client.
 
 | Header | Required | Meaning |
 | --- | --- | --- |
 | `X-Site-Key` | yes | Which shop, and with which visibility. `sfk_pub_…` publishable (safe in a browser bundle), `sfk_prv_…` preview (draft content), `sfk_sec_…` secret — **server-side only**: a secret key sent from a page is rejected with `SECRET_KEY_FROM_BROWSER`. |
-| `X-Market` | no | Market code, e.g. `se`. Omit for the site's default market. An unknown one is `MARKET_UNKNOWN`. |
-| `Accept-Language` | no | BCP-47 tag. Omit to use the market's language. |
+| `X-Market` | no | Market code, e.g. `se`. Omit on a site with one market, or for the default binding's market. Unknown or inactive is `MARKET_NOT_FOUND`, none to fall back on `MARKET_REQUIRED`. |
+| `X-Country` | no | ISO country, e.g. `DE`. Omit when the market has one country; a catalog read falls back to the market's default country, a new cart and checkout answer `COUNTRY_REQUIRED`. Outside the market it is `COUNTRY_NOT_ALLOWED`. |
+| `X-Locale` | no | Locale tag as the site spells it, e.g. `sv`. Omit for the country's default locale. Not allowed there is `LOCALE_NOT_ALLOWED`. |
+
+Take all three from the page's binding: `createStorefrontClient({ baseUrl, siteKey, binding })`. `Accept-Language` selects
+nothing and the client does not send it. Only `GET /v1/site` reads it, for `suggestedLocale`; a server can forward the
+shopper's own on that one call with `headers`. A response states its context in `context`, and a cart keeps its own: only
+`POST /v1/cart/context` moves it.
+
+The client sets these, so `params.header` is optional at every call site even though the contract marks `X-Site-Key`
+required.
+
+### Moving from markets to bindings
+
+The page's identity is now its binding (`{market}/{COUNTRY}/{locale}`), not its market:
 
-The client sets all three, so `params.header` is optional at every call site even though the contract marks
-`X-Site-Key` required.
+- `createStorefrontClient`, `createShopperClient` and `AccountActionConfig` lost `acceptLanguage`: pass `locale` or a
+  `binding`. `market` is optional on all three, and the three option types are unions, so an `interface` can no longer
+  extend them.
+- Every SEO helper and `sitemapEntries` take `binding` (a `site.bindings` id) instead of `market`, and `xDefault` is a binding
+  id. **`X-Market` matches in any case; a binding id does not**, in these helpers or in the API's `?binding=`: `SE/SE/sv`
+  throws `SeoError`, so copy the id from `site.bindings` instead of building it.
+- `alternateUrls` is gone: read `alternates`, or let the helpers do it.
+- `verifySignInAction`, `switchPrincipalAction` and `signOutAction` return `dropPrivateData` beside their result; see
+  [Accounts](#accounts-sign-in-sessions-and-saved-carts).
 
 ## Errors
 
@@ -748,17 +834,22 @@ Every operation documents `400`, `401`, `403`, `404`, `429` and `503`; the entit
 `COLLECTION_NOT_FOUND`) are called out on the operations that raise them.
 
 Codes you will meet: `SITE_KEY_MISSING`, `SITE_KEY_INVALID`, `SITE_INACTIVE`, `SECRET_KEY_FROM_BROWSER`,
-`SITE_REGISTRY_WARMING`, `MARKET_UNKNOWN`, `RATE_LIMITED` (with `retryAfterSeconds`, plus a `Retry-After`
+`SITE_REGISTRY_WARMING`, `MARKET_REQUIRED`, `MARKET_NOT_FOUND`, `COUNTRY_REQUIRED`, `COUNTRY_NOT_ALLOWED`, `LOCALE_NOT_ALLOWED`,
+`PRICE_QUERY_UNSUPPORTED`, `STOCK_QUERY_UNSUPPORTED`, `CURSOR_EXPIRED`, `SESSION_INVALID`, `PERMISSION_DENIED` (cart writes only:
+`permission` says `login` or `cart.edit`), `RATE_LIMITED` (with `retryAfterSeconds`, plus a `Retry-After`
 header), `PRODUCT_NOT_FOUND`, `COLLECTION_NOT_FOUND`, `INVALID_PAGE`, `INVALID_SINCE`, `INVALID_TYPE`, `INVALID_CURSOR`,
-`INDEX_UNAVAILABLE` (retry — a preview index is being rebuilt), `NOT_FOUND`, `INVALID_QUERY`,
+`INDEX_UNAVAILABLE` (retry — a preview index is being rebuilt), `PRICE_CONTEXT_NOT_READY` (503, `Retry-After`),
+`PRICE_CONTEXT_UNAVAILABLE` (503), `TAX_UNAVAILABLE` (503, cart add and update), `NOT_FOUND`, `INVALID_QUERY`,
 `FACET_NOT_FOUND`, `FACET_NOT_SEARCHABLE`,
 and, from the checkout ([above](#checkout)): `CART_EMPTY`, `CHECKOUT_CART_CHANGED`, `CHECKOUT_PREVIEW_KEY`,
-`CHECKOUT_MARKET_MISMATCH`, `OPTION_NOT_AVAILABLE`, `ORIGIN_NOT_ALLOWED`, `CHECKOUT_UNAVAILABLE`,
+`CONTEXT_MISMATCH`, `OPTION_NOT_AVAILABLE`, `ORIGIN_NOT_ALLOWED`, `CHECKOUT_UNAVAILABLE`,
 `CHECKOUT_PROVIDER_UNAVAILABLE`, `CHECKOUT_IN_PROGRESS`, `CHECKOUT_PROVIDER_REJECTED`, `CHECKOUT_NOT_FOUND`,
 `ORDER_NOT_FOUND`, `SITE_KEYS_SYNCING`, `CART_EXPIRED`.
 
-`SITE_REGISTRY_WARMING` and `INDEX_UNAVAILABLE` are retries, not bugs in your call, as are the checkout's
-`CHECKOUT_IN_PROGRESS`, `CHECKOUT_UNAVAILABLE`, `CHECKOUT_PROVIDER_UNAVAILABLE` and `SITE_KEYS_SYNCING` (each with `Retry-After`).
+`SITE_REGISTRY_WARMING`, `INDEX_UNAVAILABLE` and `PRICE_CONTEXT_NOT_READY` are retries, not bugs in your call, as are the checkout's
+`CHECKOUT_IN_PROGRESS`, `CHECKOUT_PROVIDER_UNAVAILABLE` and `SITE_KEYS_SYNCING` (each with `Retry-After`). `CHECKOUT_UNAVAILABLE` is a
+retry only when it carries `Retry-After`; without it the cart cannot be charged yet (a currency that is not two-decimal, or a
+quote with a rounding component), and retrying does not help.
 
 ## Warnings
 
@@ -795,8 +886,8 @@ listing — both are described under [Search-as-you-type and search-in-facet](#s
 
 ## Caching
 
-Read responses carry an `ETag` and `Vary: X-Site-Key, X-Market, Accept-Language` — the answer depends on
-all three, so a shared cache must key on all three. Send the ETag back as `If-None-Match` and a matching
+Read responses carry an `ETag` and `Vary: X-Site-Key, X-Market, X-Country, X-Locale` (`GET /v1/site` adds
+`Accept-Language`) — the answer depends on all four, so a shared cache must key on all four. Send the ETag back as `If-None-Match` and a matching
 request answers `304 Not Modified` with no body:
 
 ```ts

package/dist/account/cart.d.ts

@@ -1,6 +1,16 @@
+/**
+ * "Lägg till i sparad varukorg" (accounts spec §9.2): sign-in never merges carts, so when the shopper signs in with a browser
+ * cart A and already has a saved cart B, the frontend may offer to copy A's lines into B. The copy is ordinary
+ * `POST /v1/cart/lines` calls on B under the session, one per line of A, each with `Idempotency-Key: copy:{A}:{lineId}`:
+ * a retry (after a failure, or a second click) never doubles a line — B remembers every key it has applied.
+ */
+import type { components } from "../schema";
 import type { AccountProblem, ShopperClient } from "./index.js";
+type CartDto = components["schemas"]["CartDto"];
+type PricePairDto = components["schemas"]["PricePairDto"];
 /** Line ids of A: `copied` (added to B, or already added by an earlier run), `skipped` (the product is gone or cannot be sold:
- * `409`), `failed` (anything else — retry; the keys make copied lines no-ops). */
+ * `409`; B's context does not see it: `404 PRODUCT_NOT_FOUND`; its price is incomplete there: `503 TAX_UNAVAILABLE`), `failed`
+ * (anything else — retry; the keys make copied lines no-ops). */
 export interface CopyBrowserCartResult {
     copied: string[];
     skipped: string[];
@@ -22,3 +32,24 @@ export declare const copyKey: (browserCartToken: string, lineId: string) => stri
  * throws `CopyBrowserCartError`.
  */
 export declare function copyBrowserCart(client: ShopperClient, browserCartToken: string, savedCartToken: string): Promise<CopyBrowserCartResult>;
+/** A cart's totals as the API states them (market model §8.3, §9.1). */
+export interface CartTotals {
+    /** Before the rounding component (`grandTotal.inc − rounding`; ex and tax as the grand total's). */
+    subtotal: PricePairDto;
+    /** The rounding component as a decimal string: `"0.00"` on a gross-unit cart, a few minor units (e.g. `"-0.01"`) on a net-unit
+     * company cart; `null` when the quote is incomplete. */
+    rounding: string | null;
+    /** What the shopper pays — the receivable, rounding included. On an incomplete quote: the lines' known gross, or `inc: null`. */
+    grandTotal: PricePairDto;
+    /** `complete`, `partial` or `unavailable`: the worst line. */
+    quoteStatus: CartDto["quoteStatus"];
+    /** True until every line is completely priced and covered: checkout answers `409 CHECKOUT_CART_CHANGED` meanwhile. */
+    checkoutBlocked: boolean;
+}
+/**
+ * The cart's totals exactly as the API sends them. Never recompute them from the lines: line pairs are allocations of tax buckets, and
+ * on a net-unit cart the receivable is rounded over the whole order, so the sum of the line grosses can differ from `grandTotal.inc` by
+ * the `rounding` component (three 0.99 lines at 25 % on three booking codes: lines 3.72, rounding −0.01, grand total 3.71).
+ */
+export declare function cartTotals(cart: CartDto): CartTotals;
+export {};

package/dist/account/cart.js

@@ -32,10 +32,14 @@ export async function copyBrowserCart(client, browserCartToken, savedCartToken)
                 headers: { "X-Cart-Token": savedCartToken, "Idempotency-Key": copyKey(browserCartToken, line.id) },
                 body: { sku: line.sku, quantity: Number(line.quantity) },
             });
+            const code = problemOf(error)?.code;
             if (response.ok)
                 result.copied.push(line.id);
-            // 409 is the line's own product (PRODUCT_GONE, STOCK_INSUFFICIENT); a lost race (CART_CONFLICT) is worth a retry.
-            else if (response.status === 409 && problemOf(error)?.code !== "CART_CONFLICT")
+            // 409 is the line's own product (PRODUCT_GONE, STOCK_INSUFFICIENT); a lost race (CART_CONFLICT) is worth a retry. B's context
+            // (market model §11.1) may not see the product (404 PRODUCT_NOT_FOUND) or price it completely (503 TAX_UNAVAILABLE): no retry helps.
+            else if (response.status === 409 && code !== "CART_CONFLICT")
+                result.skipped.push(line.id);
+            else if ((response.status === 404 && code === "PRODUCT_NOT_FOUND") || (response.status === 503 && code === "TAX_UNAVAILABLE"))
                 result.skipped.push(line.id);
             else
                 result.failed.push(line.id);
@@ -46,6 +50,20 @@ export async function copyBrowserCart(client, browserCartToken, savedCartToken)
     }
     return result;
 }
+/**
+ * The cart's totals exactly as the API sends them. Never recompute them from the lines: line pairs are allocations of tax buckets, and
+ * on a net-unit cart the receivable is rounded over the whole order, so the sum of the line grosses can differ from `grandTotal.inc` by
+ * the `rounding` component (three 0.99 lines at 25 % on three booking codes: lines 3.72, rounding −0.01, grand total 3.71).
+ */
+export function cartTotals(cart) {
+    return {
+        subtotal: cart.totals.subtotal,
+        rounding: cart.totals.rounding,
+        grandTotal: cart.totals.grandTotal,
+        quoteStatus: cart.quoteStatus,
+        checkoutBlocked: cart.checkoutBlocked,
+    };
+}
 function problemOf(error) {
     return typeof error === "object" && error !== null && typeof error.code === "string" ? error : null;
 }

package/dist/account/index.d.ts

@@ -6,6 +6,7 @@
  * a client is never a module-level singleton, so one shopper's token can never serve another shopper's request.
  */
 import { type Client } from "openapi-fetch";
+import { type CommerceContextOptions } from "../context.js";
 import type { components } from "../schema";
 import type { StorefrontPaths } from "../index.js";
 export type SignInStartedDto = components["schemas"]["SignInStartedDto"];
@@ -30,25 +31,21 @@ export type AccountResult<T> = {
     problem: AccountProblem;
     retryAfter?: number;
 };
-export interface ShopperClientOptions {
+export type ShopperClientOptions = {
     /** e.g. https://api.storefront.asstio.com */
     baseUrl: string;
     /** The site's server key (`sfk_srv_…`). Server-side only. */
     serverKey: string;
-    /** Market code, e.g. "se". */
-    market: string;
     /** The request's session token (`sfs_…`) from the session cookie; omit when the shopper is signed out. */
     session?: string | null;
     /** The shopper's IP (`shopperIpFrom`); the sign-in rate limits are per shopper IP. `null` when it cannot be known. */
     shopperIp: string | null;
-    /** BCP-47 tag; omit to use the market's language. */
-    acceptLanguage?: string;
     fetch?: typeof fetch;
-}
+} & CommerceContextOptions;
 /** A client for one request. Construct it per request; never cache it beyond that request. */
 export type ShopperClient = Client<StorefrontPaths>;
 /**
- * A request-scoped client: every call carries the server key, the market, the shopper IP and (when given) the session, and
+ * A request-scoped client: every call carries the server key, the commerce context, the shopper IP and (when given) the session, and
  * every fetch is `cache: "no-store"` — an account answer is never shared or cached (spec §10.1).
  */
 export declare function createShopperClient(opts: ShopperClientOptions): ShopperClient;
@@ -95,6 +92,6 @@ export declare function getSession(client: ShopperClient): Promise<AccountResult
 export declare function getMe(client: ShopperClient): Promise<AccountResult<AccountDto>>;
 /** `GET /v1/me/company`: `403 PRINCIPAL_NOT_AVAILABLE` while the principal is the consumer. */
 export declare function getMyCompany(client: ShopperClient): Promise<AccountResult<MyCompanyDto>>;
-export { copyBrowserCart, copyKey, CopyBrowserCartError, type CopyBrowserCartResult } from "./cart.js";
+export { cartTotals, copyBrowserCart, copyKey, CopyBrowserCartError, type CartTotals, type CopyBrowserCartResult } from "./cart.js";
 export { browserCartCookie, cartCookie, cookieSecurity, readSignInCookie, serializeCookie, sessionCookie, signInCookie, type CookieSecurity, type CookieSpec, type SignInCookieValue, } from "./cookies.js";
 export { assertSameOrigin, CrossOriginError, safeReturnPath, shopperIpFrom, type HeadersLike } from "./security.js";

package/dist/account/index.js

@@ -6,8 +6,9 @@
  * a client is never a module-level singleton, so one shopper's token can never serve another shopper's request.
  */
 import createClient from "openapi-fetch";
+import { commerceHeaders } from "../context.js";
 /**
- * A request-scoped client: every call carries the server key, the market, the shopper IP and (when given) the session, and
+ * A request-scoped client: every call carries the server key, the commerce context, the shopper IP and (when given) the session, and
  * every fetch is `cache: "no-store"` — an account answer is never shared or cached (spec §10.1).
  */
 export function createShopperClient(opts) {
@@ -19,12 +20,12 @@ export function createShopperClient(opts) {
     const noStore = ((input, init) => baseFetch(input, { ...init, cache: "no-store" }));
     const client = createClient({ baseUrl: opts.baseUrl.replace(/\/$/, ""), fetch: noStore, cache: "no-store" });
     const session = opts.session || null;
+    const context = commerceHeaders(opts);
     const headers = {
         onRequest({ request }) {
             request.headers.set("X-Site-Key", opts.serverKey);
-            request.headers.set("X-Market", opts.market);
-            if (opts.acceptLanguage)
-                request.headers.set("Accept-Language", opts.acceptLanguage);
+            for (const [name, value] of context)
+                request.headers.set(name, value);
             if (opts.shopperIp)
                 request.headers.set("X-Shopper-Ip", opts.shopperIp);
             if (session)
@@ -109,6 +110,6 @@ function failure(response, error) {
 function isProblem(value) {
     return typeof value === "object" && value !== null && typeof value.code === "string";
 }
-export { copyBrowserCart, copyKey, CopyBrowserCartError } from "./cart.js";
+export { cartTotals, copyBrowserCart, copyKey, CopyBrowserCartError } from "./cart.js";
 export { browserCartCookie, cartCookie, cookieSecurity, readSignInCookie, serializeCookie, sessionCookie, signInCookie, } from "./cookies.js";
 export { assertSameOrigin, CrossOriginError, safeReturnPath, shopperIpFrom } from "./security.js";

package/dist/account/next.d.ts

@@ -1,13 +1,11 @@
 import { type AccountResult, type PrincipalDto, type ShopperClient } from "./index.js";
+import type { CommerceContextOptions } from "../context.js";
 import { type CopyBrowserCartResult } from "./cart.js";
-export interface AccountActionConfig {
+export type AccountActionConfig = {
     /** e.g. https://api.storefront.asstio.com */
     baseUrl: string;
     /** The site's server key (`sfk_srv_…`), from the server's environment. */
     serverKey: string;
-    /** Market code, e.g. "se". */
-    market: string;
-    acceptLanguage?: string;
     /** The frontend's own origin, e.g. https://shop.example: decides `Secure` and the `__Host-` prefix (dropped on http://localhost). */
     origin: string;
     /** How many proxies append to `X-Forwarded-For` in front of this server (`shopperIpFrom`). */
@@ -19,7 +17,7 @@ export interface AccountActionConfig {
      */
     cartCookie?: string;
     fetch?: typeof fetch;
-}
+} & CommerceContextOptions;
 /** What a sign-in start shows the page: no binding (it is in the cookie). */
 export interface SignInStartedView {
     challengeId: string;
@@ -37,6 +35,24 @@ export interface SignedInView {
      */
     returnPath: string | null;
 }
+/**
+ * A verify or switch that took effect says `dropPrivateData: true` (market model §18.4): the shopper is now someone else, so throw away
+ * what the browser holds from before it: cart views, prices, anything rendered for the old principal. Then read again (a cart the sign-in
+ * adopted is re-read too). A failure changed nothing, so it has no such flag.
+ */
+export type SessionTransition<T> = {
+    ok: true;
+    data: T;
+    dropPrivateData: true;
+} | (Extract<AccountResult<T>, {
+    ok: false;
+}> & {
+    dropPrivateData?: never;
+});
+/** A sign-out always says `dropPrivateData: true`: the cookies are gone whatever the API answered. */
+export type SignOutResult = AccountResult<void> & {
+    dropPrivateData: true;
+};
 /**
  * Starts a sign-in: `POST /v1/auth/sign-in`, then the binding (with the challenge id) goes into the sign-in cookie for 10
  * minutes. An unsafe `returnPath` is dropped here as the API would. The result carries the challenge id for the code form.
@@ -51,24 +67,26 @@ export interface VerifySignInActionInput {
 }
 /**
  * Verifies a code or link with the binding from the sign-in cookie: on success the session cookie is set (to the session's
- * absolute expiry) and the sign-in cookie cleared. `409 SIGN_IN_CONFIRM_REQUIRED` comes back as a problem with
- * `maskedEmail` and `siteName`; ask the shopper, then call again with `confirm: true`.
+ * absolute expiry), the sign-in cookie cleared, and the result says `dropPrivateData: true`: the guest's cart view goes, and an adopted
+ * cart is read again. `409 SIGN_IN_CONFIRM_REQUIRED` comes back as a problem with `maskedEmail` and `siteName`; ask the shopper, then
+ * call again with `confirm: true`.
  */
-export declare function verifySignInAction(config: AccountActionConfig, input: VerifySignInActionInput): Promise<AccountResult<SignedInView>>;
+export declare function verifySignInAction(config: AccountActionConfig, input: VerifySignInActionInput): Promise<SessionTransition<SignedInView>>;
 /**
- * Switches the principal: the rotated token replaces the session cookie at once (the old one serves GETs for 30 s only).
- * A failure (also `SESSION_INVALID`) is returned and leaves the cookie alone: a switch that lost to a concurrent one from
- * another tab would otherwise delete the winner's fresh cookie. Refresh the session state; only `signOutAction` clears.
+ * Switches the principal: the rotated token replaces the session cookie at once (the old one serves GETs for 30 s only), the
+ * cart cookie moves to the new principal's own cart, and the result says `dropPrivateData: true`. A failure (also `SESSION_INVALID`)
+ * is returned and leaves the cookie alone: a switch that lost to a concurrent one from another tab would otherwise delete the
+ * winner's fresh cookie. Refresh the session state; only `signOutAction` clears.
  */
-export declare function switchPrincipalAction(config: AccountActionConfig, principal: string): Promise<AccountResult<SignedInView>>;
+export declare function switchPrincipalAction(config: AccountActionConfig, principal: string): Promise<SessionTransition<SignedInView>>;
 /**
  * Signs out (`everywhere` ends every session of the account). The session cookie, the sign-in cookie, the cart cookie and the
  * browser-cart cookie are cleared whatever the API answered, and also when it cannot be reached (`{ ok: false, status: 0, problem.code: "NETWORK" }`)
- * — a session already gone is still a sign-out for this browser.
+ * — a session already gone is still a sign-out for this browser. So every answer says `dropPrivateData: true`.
  */
 export declare function signOutAction(config: AccountActionConfig, opts?: {
     everywhere?: boolean;
-}): Promise<AccountResult<void>>;
+}): Promise<SignOutResult>;
 /**
  * "Lägg till i sparad varukorg" (spec §9.2): copies the browser cart (the browser-cart cookie) into the saved cart (the cart
  * cookie, `config.cartCookie`) with `copyBrowserCart`, under the session. The browser-cart cookie is cleared only when no line