@spree/docs 0.1.306 → 0.1.308

package/dist/developer/cli/quickstart.md

@@ -249,6 +249,20 @@ spree generate migration AddPositionToSpreeBrands position:integer  # Rails buil
 
 `spree:api_resource` scaffolds the full v3 surface: model, migration, Store + Admin controllers and serializers, factory, controller specs, routes, and the `read_<resources>` / `write_<resources>` permissions that let staff roles and secret API keys reach the Admin API.
 
+### `spree filters types`
+
+Generate TypeScript declarations for your app's list filters, so the SDKs accept and autocomplete the filters and sort fields your app adds. It reads them from the running app and writes one file per run, so run it once for each app that uses an SDK, and again after you change a filter.
+
+```bash
+spree filters types --api store --out apps/storefront/src/types/spree-filters.d.ts         # @spree/sdk
+spree filters types --api admin --out apps/dashboard/src/types/spree-filters.d.ts          # @spree/admin-sdk
+spree filters types --api seller --out apps/seller-dashboard/src/types/spree-filters.d.ts  # @spree/seller-sdk
+```
+
+`--from <file>` reads the tables from `bin/rails spree:api:filter_tables` output instead of the running app.
+
+See [using your own filters from TypeScript](../core-concepts/search-filtering.md#using-your-own-filters-from-typescript).
+
 ### `spree migrate`
 
 Install pending Spree migrations from gems, then run `db:migrate` — the canonical post-update sequence.

package/dist/developer/core-concepts/external-references.md

@@ -0,0 +1,226 @@
+---
+title: External References
+description: Record the keys your ERP, PIM, DAM or CRM knows each record by, and address Spree records with those keys instead of Spree IDs.
+---
+
+## Overview
+
+When Spree is connected to other systems, the same product lives in several places at once. Your ERP knows it as `MAT-100`, your PIM as `SKU-88412`, and Spree as `prod_86Rf07xd4z`.
+
+External references are how Spree remembers those other keys. Each record can carry one key per system, and every integration can then find, create and update records using the key it already knows — without ever storing a Spree ID.
+
+They solve three problems that come up in every integration:
+
+- **Mapping.** Which Spree product is ERP item `MAT-100`?
+- **Repeatable feeds.** A nightly import cannot know whether Spree has seen a row before. Sending the same row twice must update the record, not create a duplicate.
+- **Several systems at once.** A PIM sync must never erase the key the ERP wrote.
+
+## How references are stored
+
+```mermaid
+erDiagram
+    Product ||--o{ ExternalReference : "is known as"
+    Order ||--o{ ExternalReference : "is known as"
+    Company ||--o{ ExternalReference : "is known as"
+
+    ExternalReference {
+        string system
+        string external_id
+        json metadata
+    }
+```
+
+An external reference has three parts:
+
+| Field | What it holds | Example |
+|---|---|---|
+| `system` | Which system the key belongs to | `erp`, `pim`, `netsuite` |
+| `external_id` | The key that system knows the record by | `MAT-100` |
+| `metadata` | Optional bookkeeping for the integration (a version, an etag, when it last synced) | `{ "etag": "W/\"42\"" }` |
+
+Two rules keep the mapping unambiguous, and the database enforces both:
+
+- **One key per system per record.** A product has at most one `erp` key.
+- **One record per key.** Within a store, `erp:MAT-100` names exactly one product.
+
+### System keys
+
+A system key is a short lowercase name made of letters, digits and underscores, such as `erp`, `akeneo` or `legacy_pim`. Spree lowercases and trims what you send, so `ERP` and `erp` are the same system.
+
+The system does not have to be a connected [integration](../providers/overview.md). A nightly CSV from a legacy system that has no live connection still needs somewhere to record its keys. When a connector does exist, use the same name it uses, so the connector, its references and its settings page all agree.
+
+## What can carry external references
+
+| Record | Typical source of the key |
+|---|---|
+| Products | PIM or ERP item number |
+| Variants | ERP or PIM SKU-level key |
+| Categories | PIM category code |
+| Media | DAM asset ID |
+| Stock locations | ERP warehouse code |
+| Stock levels | ERP inventory record |
+| Orders | ERP sales order number, written back after the order is sent there |
+| Companies | ERP or CRM account number (B2B) |
+| Sellers | Payout provider account, recorded by the [payout provider](../providers/payouts.md) itself |
+
+Customers are deliberately absent. A customer account can shop in more than one store, so a store-level key for it has no single owner. In B2B, the buyer's ERP identity belongs on their [company](companies.md) instead.
+
+## Writing references
+
+Send `external_references` with any create or update on the Admin API. It accepts the same map the API returns:
+
+
+```typescript Admin SDK
+const product = await adminClient.products.create({
+  name: 'Canvas Tote',
+  external_references: { erp: 'MAT-100', pim: 'SKU-88412' },
+})
+```
+
+```bash CLI
+spree api post /products -d '{
+  "name": "Canvas Tote",
+  "external_references": { "erp": "MAT-100", "pim": "SKU-88412" }
+}'
+```
+
+
+A list is accepted too, which some feeds find more natural:
+
+```json
+{
+  "external_references": [
+    { "system": "erp", "external_id": "MAT-100" },
+    { "system": "pim", "external_id": "SKU-88412" }
+  ]
+}
+```
+
+What a write changes:
+
+- **Systems you name are set.** A system the record has no key for gets one; a system it already has gets the new key.
+- **Systems you don't name are left alone.** A PIM sending only `pim` never touches the `erp` key.
+- **A blank key removes the reference.** Send `{ "erp": "" }` to unlink a record from the ERP.
+
+## Reading references
+
+Admin API responses for every record above except sellers include `external_references` as a flat map — the same shape you send:
+
+```json Response
+{
+  "id": "prod_86Rf07xd4z",
+  "name": "Canvas Tote",
+  "external_references": {
+    "erp": "MAT-100",
+    "pim": "SKU-88412"
+  }
+}
+```
+
+External references never appear in the Store API. Which ERP a merchant runs, and the keys records have in it, is back-office information.
+
+In the dashboard, references show in the **JSON** view on each record's detail page. There is no form for editing them: they are written by integrations and read by whoever is debugging a sync.
+
+## Addressing records by your keys
+
+For any record type listed in [What can carry external references](#what-can-carry-external-references), you can write `external:<system>:<key>` in the path instead of its Spree ID. An integration that only ever learned the ERP's key can then read, update and delete without first asking Spree for the record's ID.
+
+
+```typescript Admin SDK
+const product = await adminClient.products.get('external:erp:MAT-100')
+
+await adminClient.products.update('external:erp:MAT-100', {
+  name: 'Canvas Tote — Natural',
+})
+```
+
+```bash CLI
+spree api get /products/external:erp:MAT-100
+
+spree api patch /products/external:erp:MAT-100 -d '{
+  "name": "Canvas Tote — Natural"
+}'
+```
+
+
+The lookup follows the same rules as a Spree ID. It only finds records in the current store, and an API key or admin user that cannot see the record gets a `404`, exactly as they would for its Spree ID.
+
+> **WARNING:** Use this form only for keys made of letters, digits, dashes, underscores and colons. A key containing a slash or a dot cannot be part of a URL path; address that record by its Spree ID instead.
+
+## Repeatable feeds
+
+A create that names a key Spree already knows **updates that record instead of creating a new one**. A feed can therefore send every row on every run, and the result is the same as if it had sent each row once.
+
+
+```typescript Admin SDK
+// First run: creates the product.
+// Every later run: updates the same product.
+await adminClient.products.create({
+  name: 'Canvas Tote',
+  external_references: { erp: 'MAT-100' },
+})
+```
+
+```bash CLI
+spree api post /products -d '{
+  "name": "Canvas Tote",
+  "external_references": { "erp": "MAT-100" }
+}'
+```
+
+
+The update needs the same permission an ordinary update would, so a key that may create records but not edit them cannot use a create to change one.
+
+Image feeds work the same way. Media created from a URL with `external_references` is recorded under those keys, and a later run with the same key finds the existing image instead of adding a second copy.
+
+## When a key is already taken
+
+If an update names a key that already belongs to a **different** record, Spree keeps the record's other changes and answers with `422`:
+
+```json Response
+{
+  "error": {
+    "code": "conflicting_external_reference",
+    "message": "External has already been taken"
+  }
+}
+```
+
+This usually means two records in Spree map to one record in the other system — for example, a product that was duplicated by hand. Remove the reference from one of them (send a blank key), then retry.
+
+## Filtering companies by key
+
+Companies can be filtered by their references, which helps when reconciling a list of accounts against an ERP:
+
+```http
+GET /api/v3/admin/companies?q[external_references_system_eq]=erp&q[external_references_external_id_eq]=ACME-1
+```
+
+For every other record, look it up by its key with the `external:<system>:<key>` path form above.
+
+## References belong to a store
+
+A reference is owned by the store its record belongs to. Two stores can each map `erp:MAT-100` to their own product without colliding, and a key from one store never finds a record in another. A feed that serves several stores sends its rows to each store separately.
+
+## External references, custom fields or metadata?
+
+All three can hold "an ID from another system", but only one is built for it.
+
+| | External references | [Custom fields](metafields.md) | [Metadata](../customization/metadata.md) |
+|---|---|---|---|
+| **For** | A record's key in another system | Data a merchant curates | Any data your code keeps |
+| **Unique per store** | Yes, enforced | No | No |
+| **Find a record by it** | Yes, in the URL path | Through filters | No |
+| **Create-or-update by it** | Yes | No | No |
+| **Several systems at once** | Yes, one key each | One field per system | Your own structure |
+| **Store API** | Never | Configurable | Never |
+
+If an integration needs to find a record again by a key it owns, use an external reference. If a merchant should see and edit the value, use a custom field. Anything else your code needs to remember belongs in metadata.
+
+## Related
+
+- [ERP](../providers/erp.md) — feeding stock and orders from an ERP
+- [PIM](../providers/pim.md) — syncing product content from a PIM
+- [Imports & Exports](imports-exports.md) — file-based feeds
+- [Companies](companies.md) — B2B accounts and their ERP identity
+- [Admin SDK](../sdk/admin/resources.md) — the TypeScript client used in the examples

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

@@ -5,7 +5,7 @@ description: Add your own structured, typed data to products, orders and other r
 
 ## Overview
 
-Sooner or later you need to store something Spree doesn't have a field for. A fabric composition. A care instruction. A gift message. An ID from the system you sync with.
+Sooner or later you need to store something Spree doesn't have a field for. A fabric composition. A care instruction. A gift message.
 
 Custom fields are how you do that without changing the database. You declare a field once — its name, its type, who can see it — and from then on it can be set on any record of that kind, edited in the dashboard, returned by the API, and searched or filtered like any built-in field.
 
@@ -209,11 +209,12 @@ Spree has two ways to store your own data, and they are not competing — they s
 | **Visibility** | Configurable per field | Never read by the Store API |
 | **Searchable** | Yes, opt in | Not through the product search |
 
-Put it simply: **custom fields are for people, metadata is for machines.** If a merchant should type it, define a custom field. If it is a sync token or an external ID that only your integration reads, use metadata.
+Put it simply: **custom fields are for people, metadata is for machines.** If a merchant should type it, define a custom field. If it is a sync token that only your integration reads, use metadata. If it is the key another system knows the record by, use an [external reference](external-references.md).
 
 ## Related
 
 - [Metadata](../customization/metadata.md) — the machine-readable alternative
+- [External References](external-references.md) — keys from your ERP, PIM or CRM
 - [Products](products.md) — the most common place for custom fields
 - [Search & Filtering](search-filtering.md) — how filters and search work
 - [Admin SDK](../sdk/admin/resources.md) — managing definitions and values in TypeScript

package/dist/developer/core-concepts/search-filtering.md

@@ -245,6 +245,91 @@ The Store API uses query parameters prefixed with `q[]` for filtering any resour
 
 > **INFO:** Only attributes explicitly allowed by each resource can be used for filtering. Attempting to filter on unsupported fields will be silently ignored.
 
+### Making a field filterable
+
+A resource's filters come from its model's allowlists, and nowhere else. Spree generates its API reference and SDK types from them, so the [Querying](../../api-reference/admin-api/querying.md#which-filters-an-endpoint-accepts) reference lists what core declares. Filters your app adds take effect in the API immediately; to use them from TypeScript, declare them as shown below, since the published SDK types are generated from core alone.
+
+```ruby server/config/initializers/spree.rb
+Spree.ransack.add_attribute(Spree::Product, :erp_id)
+Spree.ransack.add_association(Spree::Product, :brand)
+Spree.ransack.add_scope(Spree::Product, :featured, type: 'boolean')
+Spree.ransack.add_scope(Spree::Product, :by_brand, type: 'id')
+```
+
+Give a model a `search` filter (`q[search]=term`) by naming the attributes it matches, partially and case-insensitively. Attributes of associated records are named with the association as a prefix:
+
+```ruby server/app/models/spree/brand_decorator.rb
+base.search_by :name, :code
+```
+
+`search` is offered to the Store and Seller APIs only when each attribute it matches is one that API may filter on. The API reference describes it from the attributes.
+
+Declare the `type` of a scope's argument: `'boolean'` for a scope taking none (`q[featured]=true`), or `'text'`, `'id'`, `'decimal'`, `'integer'`, `'date'` or `'datetime'` for one value. A list of kinds (`%w[decimal decimal]`) means several arguments in order, and `{ list: 'id' }` means any number of them. A scope declared without a type is published as taking one text value.
+
+Every entry is a filter any caller of that API can run. Keep back-office fields out of the Store API with `private_ransackable_attributes`, and add associations the storefront may filter through to `storefront_ransackable_associations`.
+
+### Using your own filters from TypeScript
+
+The SDKs type each `list()` call with the filters Spree itself declares. A filter your app adds works in the API at once, but TypeScript rejects it until it is declared, because the published types cannot know about it. There are three ways to use it.
+
+**Generate the declarations (recommended).** This reads your app's filters, the ones Spree declares and the ones you added, and writes a declaration file for one SDK. Each frontend uses its own SDK, so generate a file for each app in your project, from the project root:
+
+| App | SDK | `--api` |
+|---|---|---|
+| `apps/storefront` | `@spree/sdk` | `store` |
+| `apps/dashboard` | `@spree/admin-sdk` | `admin` |
+| `apps/seller-dashboard` (marketplaces) | `@spree/seller-sdk` | `seller` |
+
+**Spree CLI:**
+
+```bash
+    spree filters types --api store --out apps/storefront/src/types/spree-filters.d.ts
+    spree filters types --api admin --out apps/dashboard/src/types/spree-filters.d.ts
+    spree filters types --api seller --out apps/seller-dashboard/src/types/spree-filters.d.ts
+    ```
+
+  **Without CLI:**
+
+```bash
+    cd server
+    bin/rails spree:api:filter_tables > ../filter-tables.json
+    cd ..
+    npx @spree/cli filters types --from filter-tables.json --api store --out apps/storefront/src/types/spree-filters.d.ts
+    npx @spree/cli filters types --from filter-tables.json --api admin --out apps/dashboard/src/types/spree-filters.d.ts
+    npx @spree/cli filters types --from filter-tables.json --api seller --out apps/seller-dashboard/src/types/spree-filters.d.ts
+    ```
+
+
+Run them again after you add or change a filter, and commit the generated files with the app code that uses them. Match `--api` to the app: a storefront file generated with `--api admin` compiles, but declares the Admin API's filters. After that, every `list()` call accepts and autocompletes your filters and sort fields, and a misspelled one is still a compile error.
+
+**Send it unchecked.** Filters inside `q` are sent as given, without type checking or autocomplete:
+
+```typescript
+await client.products.list({
+  name_cont: 'shirt',
+  q: { erp_id_eq: 'ERP-1' },
+})
+```
+
+**Declare it by hand.** Each resource has an empty interface in the SDK (`ProductFilterExtensions`, `OrderFilterExtensions`, …) that is part of its filter type, and TypeScript [merges your declaration](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation) into it. The file must contain an `import` or `export`; without one, it replaces the SDK's types instead of adding to them:
+
+```typescript src/types/spree.d.ts
+export {}
+
+declare module '@spree/sdk' {
+  interface ProductFilterExtensions {
+    erp_id_eq?: string
+    featured?: boolean
+  }
+  // Sort fields, as keys
+  interface ProductSortExtensions {
+    erp_id: true
+  }
+}
+```
+
+Name each filter the way the API receives it, with its predicate (`erp_id_eq`, `erp_id_in` for a list) or a scope by its name. Type amounts as decimal strings, counts as numbers and flags as booleans.
+
 ## Pagination
 
 All list endpoints support pagination:

package/dist/developer/how-to/build-a-b2b-store.md

@@ -877,7 +877,7 @@ To add your own B2B cards, such as a credit account or an ERP reference, the com
 The B2B building blocks are ordinary Spree resources, so the usual customization paths apply:
 
 - **Events.** Companies, company invitations and catalogs publish lifecycle events, and orders publish `order.placed`. Subscribe to them to sync accounts and orders with an ERP or CRM. See [Events](../core-concepts/events.md).
-- **External references.** Companies accept `external_references`, so an ERP can address a company by its own account number.
+- **[External references](../core-concepts/external-references.md).** Companies accept `external_references`, so an ERP can address a company by its own account number.
 - **Tax identifier validators.** Register a validator that checks numbers against a live registry.
 - **Checkout requirements.** Register an extra requirement, such as "a cost center is required", and it appears in the cart's `requirements` next to the built-in ones. See [Checkout customization](../customization/checkout.md).
 

package/dist/developer/providers/erp.md

@@ -26,7 +26,7 @@ Two ways in, both writing stock movements rather than overwriting numbers — so
 
 ## Addressing records by your keys
 
-The same product is known to your ERP and your PIM under different keys. External references are store-scoped mappings that let any feed address a Spree record as `external:<system>:<id>` — a create that names a key Spree already knows updates that record instead of failing.
+The same product is known to your ERP and your PIM under different keys. External references are store-scoped mappings that let any feed address a Spree record as `external:<system>:<id>` — a create that names a key Spree already knows updates that record instead of failing. See [External References](../core-concepts/external-references.md).
 
 ## Checkout holds and failure policy
 

package/dist/developer/providers/payouts.md

@@ -179,7 +179,7 @@ If your rails have no idempotency keys, look the movement up by that key (or by
 
 ## Seller accounts
 
-A seller's account with your provider is stored as an [external reference](erp.md#addressing-records-by-your-keys) filed under your `reference_system`, so a marketplace that migrates between providers keeps every account on record:
+A seller's account with your provider is stored as an [external reference](../core-concepts/external-references.md) filed under your `reference_system`, so a marketplace that migrates between providers keeps every account on record:
 
 | Need | Call |
 |---|---|

package/dist/developer/providers/pim.md

@@ -11,7 +11,7 @@ Your PIM owns product content — names, descriptions, attributes, associations,
 
 ## Product data feeds
 
-Products, variants and prices flow in through the Admin API and CSV imports. Feeds address records by the keys your PIM already uses via external references (`external:<system>:<id>`), so an integration never has to store Spree IDs to update what it created.
+Products, variants and prices flow in through the Admin API and CSV imports. Feeds address records by the keys your PIM already uses via [external references](../core-concepts/external-references.md) (`external:<system>:<id>`), so an integration never has to store Spree IDs to update what it created.
 
 ## The pricing provider
 

package/dist/developer/tutorial/model-and-api.md

@@ -169,7 +169,7 @@ attribute(:brand_id) { |product| product.brand&.prefixed_id }
 has_one :brand, serializer: Spree::Api::V3::BrandSerializer
 ```
 
-The model has to allow filtering by it, or `?q[brand_id_eq]=…` is rejected:
+The model has to allow filtering by it, or `?q[brand_id_eq]=…` is ignored:
 
 ```ruby server/app/models/spree/product_decorator.rb
 base.whitelisted_ransackable_attributes |= %w[brand_id]

package/dist/developer/upgrades/5.6-to-6.0.md

@@ -992,6 +992,55 @@ Both internal-note serializers now return the pair. Previously orders exposed on
 
 Stored markup is also held to a narrower allowlist than 5.6 — see [the rich-text migration](#move-rich-text-out-of-action-text) for what is permitted and how to widen it.
 
+## Upgrading a storefront
+
+A storefront built on the Store API and `@spree/sdk`, such as the [Spree storefront](https://github.com/spree/storefront), needs `@spree/sdk` 2.0 and the changes below. Most are type errors that point at the line to change.
+
+### List filters and sort are typed
+
+Each `list()` method now takes the filters and sort fields its endpoint accepts. A misspelled filter, a filter the endpoint doesn't support, or an unknown sort field used to return the unfiltered list; it is now a compile error. `ProductListParams`, `CategoryListParams`, `CollectionListParams` and `OrderListParams` keep their names but no longer accept arbitrary keys.
+
+- **A sort value read from the URL is a plain `string`.** Narrow it where you read it; the API still validates the value at runtime:
+
+  ```ts src/lib/utils/product-query.ts
+  import type { ProductListParams, ProductSort } from '@spree/sdk'
+
+  params.sort = filters.sortBy as ProductSort
+  ```
+
+- **Filters your backend adds are compile errors until you declare them.** The published types list only the filters Spree itself declares. Any filter or scope your backend adds (through `Spree.ransack.add_attribute`, `add_scope` or a model decorator) still works in the API, but TypeScript rejects the key. Generate the declarations from your app, and run the command again whenever a filter changes:
+
+  ```bash
+  spree filters types --api store --out apps/storefront/src/types/spree-filters.d.ts
+  ```
+
+  Generate one for the dashboard (`--api admin --out apps/dashboard/src/types/spree-filters.d.ts`) and the seller panel (`--api seller`) too, if they use your filters. For a one-off filter, send it inside `q` instead (`list({ q: { erp_id_eq: 'ERP-1' } })`), which is not type checked. See [using your own filters from TypeScript](../core-concepts/search-filtering.md#using-your-own-filters-from-typescript) for both, and for declaring filters by hand.
+
+- **Amount filters take decimal strings.** `price_gte`, `price_lte` and the other money filters are typed as strings, like every money value in 6.0. Send `'20.00'`, not `20`.
+
+- **Prefer `search`.** Products, categories and collections take `q[search]` (the SDK's `search` key), which matches more than `name_cont`. See [which filters an endpoint accepts](../../api-reference/store-api/querying.md#which-filters-an-endpoint-accepts).
+
+### Completing a cart can return an order group
+
+`carts.complete()` returns `Order | OrderGroup`. In a marketplace, a cart holding several sellers' goods divides into one order per seller and returns the group. Narrow the result with `isOrderGroup` before reading order fields:
+
+```ts
+import { isOrderGroup } from '@spree/sdk'
+
+const result = await client.carts.complete(cartId)
+const orders = isOrderGroup(result) ? result.orders : [result]
+```
+
+### Other Store API changes to check
+
+| Change | What to update | Details |
+|---|---|---|
+| Delivery requirement renamed | Match `delivery_method` (field) and `delivery_method_required` (code) instead of `shipping_method` | [Checkout without a state machine](#checkout-without-a-state-machine) |
+| Type values are short names | Compare `payment_source_type` with `credit_card`, and read custom field `field_type` | [Type values are short names](#type-values-are-short-names-not-class-names) |
+| Rich text comes in two shapes | Render `description_html` for markup; `description` is plain text | [Rich-text fields](#rich-text-fields-read-as-plain-text-plus-html) |
+| Payment source IDs | Stored `source_id` values change prefix from `ps_` to `psrc_` | [Payment source IDs](#payment-source-ids-use-the-psrc_-prefix) |
+| Completed carts are read-only | Read post-checkout data from the order, not the cart | [The Cart/Order split](#the-cartorder-split) |
+
 ## For extension authors
 
 - **Don't reach for model business methods from services** — 6.0 code style writes behavior inline in service/workflow steps; models keep data, validations, predicates and persistence primitives. Extensions patching removed model methods (`finalize!` internals, updater hooks) should move to workflow hooks (`Spree.hooks.register('carts.complete.before_finalize') { |flow| ... }` — handlers receive the workflow instance) or event subscribers.

package/package.json

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