@spree/docs 0.1.277 → 0.1.279

package/dist/api-reference/store-api/localization.md

@@ -128,6 +128,16 @@ Each value is resolved in the following order:
 
 > **NOTE:** The locale and currency must be supported by the current store. If an unsupported value is provided, the API falls back to the store's default.
 
+### Caching
+
+Cacheable guest responses (products, categories, collections, markets, locales, currencies, policies, sellers) are sent with `Cache-Control: public` and:
+
+```
+Vary: Accept, X-Spree-Api-Key, Authorization, X-Spree-Country, X-Spree-Currency, X-Spree-Locale, X-Spree-Channel
+```
+
+A CDN or shared cache therefore stores one copy per country, currency, locale and channel, so a visitor in one market never receives another market's prices. The `country`, `currency` and `locale` query parameters are part of the URL, so they are cached separately without needing `Vary`. Responses to signed-in customers are `Cache-Control: private, no-store`.
+
 ## Translated Content
 
 When a locale is set, all translatable fields are returned in the requested language. This includes product names, descriptions, category names, and other content managed through [translations](../../developer/core-concepts/translations.md).

package/dist/developer/core-concepts/pricing.md

@@ -220,7 +220,7 @@ When resolving prices, Spree considers the full context of the request:
 
 The Store API automatically builds this context from the [request headers](../../api-reference/store-api/localization.md) (`X-Spree-Currency`, `X-Spree-Country`) and authentication state. You don't need to construct it manually — just make API requests and the correct price is resolved.
 
-> **INFO:** Price resolution runs per request — there is no in-process caching of resolved prices. The Store API instead relies on HTTP/CDN caching, with `Vary` headers keyed on the `X-Spree-Currency` and `X-Spree-Locale` request headers so each currency/locale combination is cached separately at the edge.
+> **INFO:** Price resolution runs per request — there is no in-process caching of resolved prices. The Store API instead relies on HTTP/CDN caching, with `Vary` headers keyed on every request header that changes the price — `X-Spree-Country` (market), `X-Spree-Currency`, `X-Spree-Locale`, `X-Spree-Channel`, the publishable key and `Authorization` — so each combination is cached separately at the edge. See [HTTP caching](../deployment/caching.md#http-caching-of-store-api-responses).
 
 ## Time-Based Pricing
 

package/dist/developer/deployment/caching.md

@@ -23,6 +23,23 @@ config.cache_store = :redis_cache_store, { url: ENV["REDIS_URL"] }
 
 Works identically with Redis or Valkey (the Linux Foundation fork most hosting platforms now provision).
 
+## HTTP caching of Store API responses
+
+Read-only Store API endpoints (products, categories, collections, markets, locales, currencies, policies, sellers) are HTTP-cacheable for guests, so a CDN or reverse proxy in front of Spree can serve them from the edge:
+
+- **Guests** get `Cache-Control: public, max-age=300` (list endpoints add `stale-while-revalidate=30`) plus an `ETag`, and conditional requests return `304 Not Modified`.
+- **Signed-in customers** (a customer JWT in `Authorization`) get `Cache-Control: private, no-store` — nothing is cached.
+
+Guest responses carry this `Vary` header:
+
+```
+Vary: Accept, X-Spree-Api-Key, Authorization, X-Spree-Country, X-Spree-Currency, X-Spree-Locale, X-Spree-Channel
+```
+
+Each of these headers changes the response body: the publishable key selects the store, `X-Spree-Country` selects the market (currency, prices, tax display, availability), and `X-Spree-Channel` controls price visibility and which products are listed. `Authorization` keeps a cached guest response from being served to a signed-in customer.
+
+> **WARNING:** If your CDN ignores `Vary` or builds its own cache key (for example Cloudflare Cache Rules with a custom cache key), include every header listed above in that key, or it serves one market's or store's prices to another.
+
 ## Testing Locally
 
 To enable caching in the development environment:

package/dist/developer/deployment/cdn.md

@@ -6,6 +6,8 @@ description: >-
 
 To improve performance of your Spree application, we recommend using a CDN (Content Delivery Network) to cache images and static files.
 
+> **NOTE:** If you also cache Store API responses at the CDN, the cache key must include every header in the response's `Vary` header — see [HTTP caching of Store API responses](caching.md#http-caching-of-store-api-responses).
+
 We recommend using [Cloudflare](https://www.cloudflare.com/) as your CDN provider. It's free and simple to set up.
 
 After setting up your Cloudflare account and adding your domain name to Cloudflare, you will need to set your cache settings.

package/dist/developer/how-to/build-a-marketplace.md

@@ -714,9 +714,16 @@ const tokens = await sellerClient.auth.login({
 sellerClient.setToken(tokens.token)
 
 // A user who runs several sellers picks which one they are acting as
-sellerClient.setSeller('sel_xxx')
+const { sellers } = await sellerClient.me.get()
+sellerClient.setSeller(sellers[0].id)
+
+// The signed-in person edits their own account (name, photo, panel language);
+// the seller business itself is `sellerClient.profile.update(...)`
+await sellerClient.me.update({ first_name: 'Ada', selected_locale: 'de' })
 ```
 
+> **NOTE:** `sellerClient.me` is an object with `get()` and `update()`. Code written against `@spree/seller-sdk` 1.0.0-beta.1 or beta.2 that calls `sellerClient.me()` directly keeps working, but that form is deprecated and logs a one-time warning — switch to `sellerClient.me.get()`.
+
 Authentication is JWT only. **There is deliberately no secret-key equivalent**: a key that acts as a seller without a seller signing in is exactly what the Seller API's design exists to prevent. Sign-in fails for a store staff member who runs no seller, even though staff share the same user class.
 
 The chosen seller travels as `X-Spree-Seller-Id`. The store is derived from the seller server-side and never sent alongside, so no header a client can set widens what it reaches.

package/dist/developer/how-to/custom-delivery-rate-provider.md

@@ -93,13 +93,19 @@ module SpreeAcmeCarrier
     # One API call serves every delivery method sharing this provider within
     # a request — carriers return all services in one response, so quoting
     # five methods should not mean five round-trips.
+    #
+    # Key the cache on everything the request sends, not on the location and
+    # order: an order split into several packages from one stock location
+    # would otherwise get the first package's rates for every package.
+    # Digesting the payload itself keeps the key complete as the request grows.
     def quotes_for(package)
-      key = [:acme_quotes, store.id, package.stock_location.id, package.order.id]
-      Spree::Current.provider_cache[key] ||= integration.client.rates(
-        from: package.stock_location,
-        to: package.order.ship_address,
-        parcel: { weight: package.weight }
-      )
+      request = {
+        from: package.stock_location.slice(:address1, :city, :zipcode, :country_id),
+        to: package.owner.ship_address.slice(:address1, :city, :zipcode, :country_id),
+        parcel: { weight: package.weight.to_f }
+      }
+      key = [:acme_quotes, store.id, Digest::SHA256.hexdigest(request.to_json)]
+      Spree::Current.provider_cache[key] ||= integration.client.rates(**request)
     end
   end
 end

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.277",
+  "version": "0.1.279",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",