@spree/docs 0.1.227 → 0.1.229

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

@@ -35,6 +35,7 @@ A query names what to measure and how to slice it. This is the whole surface:
   "filters": [{ "dimension": "channel", "op": "eq", "value": "ch_86Rf07xd4z" }],
   "time_range": { "preset": "last_4_weeks" },
   "compare": "previous_period",
+  "currency": "EUR",
   "sort": "-total_sales",
   "limit": 50
 }
@@ -47,6 +48,7 @@ A query names what to measure and how to slice it. This is the whole surface:
 | `filters` | `eq` or `in` against a dimension. Values are prefixed IDs where the dimension identifies a record. |
 | `time_range` | A named preset, or `since`/`until` as ISO 8601. A bare date covers the store's whole day. |
 | `compare` | `previous_period` adds `previous` and `growth` to every metric. |
+| `currency` | ISO 4217 code, e.g. `"EUR"`. Defaults to the store's own. Applies only to a query containing money — see [Metrics](#metrics). The values a store accepts are in the schema's `supported_currencies`. |
 | `sort` / `limit` | Ranking controls; ignored for time series, which are always chronological and complete. |
 
 Unknown members are rejected, never dropped. A malformed query answers 422,
@@ -88,12 +90,20 @@ Spree.reporting.metric :total_sales,
   a `:percent` metric arrives as the number a merchant reads (`42.5`), not the
   fraction.
 
-  Amounts are **never converted**. A query answers in one currency — the one
-  it names, or the store's default — and every base a money metric reads must
-  filter by it, or two currencies end up added together under one symbol. A
-  store selling in several therefore has as many answers as it has
-  currencies, which is why the home screen offers a currency alongside its
+  Amounts are **never converted**. A query containing money answers in one
+  currency — the one it names, or the store's default — and every base a money
+  metric reads filters by it, or two currencies end up added together under one
+  symbol. A store selling in several therefore has as many money answers as it
+  has currencies, which is why the home screen offers a currency alongside its
   channel and date range.
+
+  **A query with no money in it is not scoped to a currency at all.** Counts
+  and quantities — orders, customers, units sold, payments taken — are not
+  amounts, so narrowing them would answer "how many orders did we take" with
+  only the share that happened to be priced in one currency. Ask for `orders`
+  alone and you get every order; ask for `orders` beside `total_sales` and the
+  whole query narrows, because the money figure has to. A ratio counts as
+  money when either side is: average order value does, sell-through does not.
 - `ratio: [:numerator, :denominator]` defines a **derived** metric, computed
   after aggregation so it is correct for both rows and totals. Average order
   value is `ratio: %i[total_sales orders]`, never `AVG()`.

package/dist/developer/how-to/extend-reporting.md

@@ -198,6 +198,18 @@ These are limits of the compiler, not of registration:
 Registering a base is otherwise ordinary: declare its family, its table, a
 store-scoped relation, its time column and which bases its dimensions reach.
 
+The relation's `currency` argument **is nil when the query contains no money
+metric**, and a base must then not filter by it — a count restricted to one
+currency is a wrong answer, not a narrower one. Guard the filter rather than
+passing nil into `where`, which would match nothing:
+
+```ruby
+relation: lambda { |store, range, currency|
+  scope = store.subscriptions.where(created_at: range)
+  currency ? scope.where(currency: currency) : scope
+}
+```
+
 ```ruby
 Spree.reporting.base :subscriptions, family: :subscriptions,
   table: '%{subscriptions}',

package/package.json

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