@spree/docs 0.1.306 → 0.1.307

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/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/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.307",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",