Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Added the typed filters plan with its open questions settled
Damian Legawiecb62285c065a6
diff --git a/docs/plans/6.0-typed-filters.md b/docs/plans/6.0-typed-filters.mdnew file mode 100644index 0000000000..0dd6beeb08--- /dev/null+++ b/docs/plans/6.0-typed-filters.md@@ -0,0 +1,150 @@+# Typed Filters from Ransack Declarations++**Status:** In Progress — PR A (filter tables, filters in OpenAPI, generated SDK filter and sort types) being built 2026-10-09; PR B and PR C not started+**Target:** Spree 6.0+**Depends on:** nothing unbuilt. Decimal values are already strings in the generated SDK types.+**Author:** Damian + Claude+**Last updated:** 2026-10-09+**Tracking:** Linear V-3740 · GitHub spree/spree#14851++## Summary++List endpoints filter through Ransack's `q[...]` parameters, but the contract for those filters exists only inside Ransack. The OpenAPI specs list 83 filter parameters on the Admin API and 20 on the Store API. Ransack accepts any predicate on any of the 157 ransackable declarations, follows associations to any depth, and silently ignores keys it does not recognize. A mistyped filter therefore returns the unfiltered list. The dashboard already depends on undocumented forms: `_or_` combinations (`name_or_code_cont`), association paths (`stock_level_stock_location_id_eq`) and `_start` / `_in` predicates. The SDK filter types are written by hand and drift from both.++This plan keeps the existing Ruby declarations exactly as they are (`whitelisted_ransackable_*`, `private_ransackable_*`, `storefront_ransackable_associations`) and generates the contract from them:+- a machine-readable filter table per endpoint in OpenAPI;+- fully typed filter and sort parameters in every SDK;+- a conformance suite.++Ransack rejects unknown filters with a 400 instead of ignoring them. Nothing about how filters are declared or executed is reinvented. Ransack stays the engine, and the model allowlists stay the only place filters are declared.++## Key Decisions (do not deviate without discussion)++- **No new filter DSL.** The model allowlists remain the single source. The only addition is an optional `ransackable_scope_types` hash next to `whitelisted_ransackable_scopes`, because a scope's argument types cannot be read from Ruby. An undeclared scope type falls back to `string`.+- **Ransack remains the engine and the wire syntax.** `q[attribute_predicate]=value` and `sort=-field` stay exactly as they are. No client changes how it sends filters.+- **Everything the contract needs is read from what exists:**++ | Source | Provides |+ | --- | --- |+ | `ransackable_attributes / associations / scopes(auth_object)` | What each audience may filter: admin (`nil`), `:store`, `:seller` |+ | `columns_hash[name].type`, Mobility translated attribute names | Value kind of each attribute |+ | `has_status` value lists | Enum values (reusing the generated status types) |+ | `*_id` columns, polymorphic `*_type` columns | Prefixed ID and short-name values, already decoded by `ResourceController` |+ | `ransacker` declarations | Their declared type |+ | Rails routes → index controller → `model_class`, `ransack_auth_object` | Which table applies to which endpoint |++- **Predicates are a fixed set per value kind,** pinned in one constant (`Spree::Api::V3::FilterPredicates`), not "everything Ransack supports":++ | Value kind | Predicates |+ | --- | --- |+ | text | `eq` `not_eq` `in` `not_in` `cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |+ | decimal, integer, date, datetime | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |+ | enum, prefixed ID, short-name type | `eq` `not_eq` `in` `not_in` `null` `not_null` |+ | boolean | `eq` `true` `false` `null` |++ A predicate outside the set for its kind is rejected, even when Ransack would accept it.+- **Associations are typed and accepted to depth 2.** Depth 2 covers the dashboard's deepest filter today (`sku_or_variant_product_name_cont` on stock items). Each hop uses the associated model's own allowlist for the same audience. Deeper paths are rejected. The Store and Seller APIs already expose only `storefront_ransackable_associations`, so their tables stay small.+- **`_or_` combinations stay supported, typed loosely.** They are plain Ransack. Every part must be a declared text attribute of the same model, and all parts share one predicate. In TypeScript they are accepted through a template-literal index signature (`` `${string}_or_${string}` ``). New code prefers a `search` scope.+- **Unknown filters are errors.** `ResourceController#collection` calls Ransack with `ignore_unknown_conditions: false` and also checks keys against the generated table, which enforces the predicate set and the depth limit. Any violation returns 400 `invalid_filter`, naming the key. The same applies to `sort`. Breaking for clients sending dead keys: upgrade guide.+- **OpenAPI carries a compact table, not expanded parameters.** Each list endpoint declares one `q` parameter (`style: deepObject`) and an `x-spree-filters` extension: attributes with their kinds, associations by name, scopes with their argument types, and sortable fields. Expanding attribute × predicate × association into named parameters would add thousands of lines per spec.+- **SDK types are expanded from the table by shared mapped types,** generated without a database:++```ts+ export type OrderFilters =+ TextFilters<'number' | 'email' | 'coupon_code'>+ & RangeFilters<'total' | 'item_total', DecimalString>+ & RangeFilters<'completed_at', IsoDateTime>+ & EnumFilters<'status', OrderStatus>+ & IdFilters<'customer_id' | 'channel_id'>+ & BooleanFilters<'considered_risky'>+ & Prefixed<'line_items_', LineItemFilters>+ & OrFilters+ & { complete?: boolean; search?: string }+ export type OrderSort = SortKey<'number' | 'total' | 'completed_at'>+```++ `TextFilters<'number'>` yields `number_eq?: string`, `number_in?: string[]`, `number_null?: boolean` and so on. List methods take `ListParams<OrderFilters, OrderSort>`. `transformListParams` already maps these keys to `q[...]`, so the SDK runtime does not change.+- **Each API gets its own types.** The generator calls the same allowlists with each audience's auth object, so `@spree/sdk`, `@spree/seller-sdk` and `@spree/admin-sdk` see exactly what their API accepts. Private attributes never appear in a public type.+- **Seller filters reach no associations (2026-10-09).** The Seller API keeps today's behaviour: a restricted audience other than `:store` gets an empty association list, so the seller tables hold the model's own attributes and scopes only. A seller list needing a related filter declares a scope. Rejected: a separate `seller_ransackable_associations` list (each entry is a join a seller can probe and needs its own review), and reusing the storefront list (widening one audience would silently widen the other).+- **`_in` / `_not_in` take arrays only (2026-10-09).** `q[key][]=a&q[key][]=b`, or the indexed hash form, is the only encoding. Ransack never split comma-separated strings, so `q[status_in]=a,b` already matched nothing; PR C turns it into a 400. Rejected: splitting commas on the server, which makes a value containing a comma unfilterable.+- **No 5.x deprecation release (2026-10-09).** 6.0 is a major version. The upgrade guide documents the change, and PR C adds a `Spree.api.strict_filters` setting (default on) that a store can switch off for one release while it fixes its integrations. Rejected: a 5.x warning header (maintenance-branch work and a separate release) and strict-only with no setting.+- **This run builds PR A only (2026-10-09).** PR B's logging belongs to Spree Cloud, and PR C waits for what it finds.+- **One direction of generation.** Model declarations → the swaggerize run (which already has a database, so the rule against `typelize_from` still holds) → `x-spree-filters` in `docs/api-reference/*.yaml` → SDK types. CI fails when the committed SDK filter types do not match the specs.++## Design Details++### Generator++`Spree::Api::V3::FilterTable.for(controller_class)` returns a plain data structure for one endpoint:++```ruby+{+ attributes: { 'number' => :text, 'total' => :decimal, 'status' => { enum: Spree::Order::STATUSES } },+ associations: { 'line_items' => 'LineItem', 'customer' => 'Customer' },+ scopes: { 'complete' => [:boolean], 'search' => [:text] },+ sortable: %w[number total completed_at]+}+```++It is built from the model allowlists for the controller's `ransack_auth_object`. Association targets refer to other tables by name, so each model's table is computed once. Translated attributes (Mobility) are text. A column the generator cannot classify fails the generator spec.++`swagger_helper` exposes `filter_parameters_for(controller_class)`. Every list endpoint's integration spec calls it, so no spec lists `q[...]` parameters by hand again. The rswag run writes `x-spree-filters` deterministically, under the existing frozen-clock setup.++### Runtime check++`ResourceController#ransack_params` validates each key against the endpoint's `FilterTable`: attribute or association path, predicate allowed for the value kind, depth at most 2, `_or_` parts all declared text attributes, scope declared. Ransack then runs with `ignore_unknown_conditions: false` as a second guard. The table is memoized per controller class. Both failures render 400 `invalid_filter` through `ErrorHandler`.++### SDK generation++A Node script in `sdk-core` reads `x-spree-filters` from each spec and writes `src/types/generated/filters/*.ts` into the matching SDK. The shared mapped types (`TextFilters`, `RangeFilters`, `EnumFilters`, `IdFilters`, `BooleanFilters`, `Prefixed`, `OrFilters`, `SortKey`) live in `sdk-core`. Zod schemas for filters come from the existing `generate:zod` step. The hand-written filter interfaces in `packages/sdk/src/types/index.ts` are deleted.++### Conformance suite++Generated from the same tables, and run per endpoint:+- For each declared attribute, one predicate per value kind returns 200, and a factory record that should match does match.+- Each scope runs with its declared argument types.+- A depth-2 association path works.+- An undeclared attribute, an undeclared predicate, a depth-3 path and an undeclared sort field each return 400 `invalid_filter`.++This is the black-box specification a non-Ruby implementation must pass. It needs Ransack's semantics only for this finite table.++## Migration Path++**PR A: table and types (no behaviour change)**+1. Add `FilterPredicates`, `FilterTable` and `ransackable_scope_types` (optional), with a spec that fails for any list endpoint whose table cannot be built.+2. Add `filter_parameters_for` to `swagger_helper`; replace the hand-written `q[...]` parameters in integration specs; regenerate the specs with `x-spree-filters`.+3. Generate SDK filter types; type every list method with `ListParams<Filters, Sort>`; delete the hand-written filter interfaces.+4. Type-check the dashboard and seller dashboard against the new types. Every undeclared filter they use surfaces as a compile error and gets fixed by declaring it on the model or switching to a scope.++**PR B: inventory**+1. Log undeclared `q` keys on Spree Cloud for two weeks, behind a flag, to catch agency and integration usage a grep cannot see.+2. Fix or declare everything found. Controllers that rewrite `q` by hand (products, tags, store credits) move to scopes so their tables are accurate.++**PR C: enforcement and conformance (breaking)**+1. Runtime check plus `ignore_unknown_conditions: false`; 400 `invalid_filter`.+2. Generated conformance suite.+3. Docs: one filtering page explaining predicates per value kind, `_or_`, depth and sorting, linked from each list endpoint. Upgrade guide entry (unknown filters now fail; deeper paths and unlisted predicates removed). Changelog. SDK changeset.++Verification per PR: `pnpm test:changed`, then `pnpm test:rspec api`; `pnpm typecheck` and `pnpm test` for `packages/sdk`, `packages/admin-sdk`, `packages/seller-sdk`, `packages/dashboard` and `packages/seller-dashboard`; dashboard e2e for list filtering.++## Constraints on Current Work++- Declare filterable attributes, associations and scopes on the model allowlists only. Never parse `params[:q]` by hand in a controller; add a scope instead.+- A new scope taking an argument adds its types to `ransackable_scope_types`.+- Never hand-write `q[...]` parameters in an integration spec; use `filter_parameters_for`.+- Never hand-write SDK filter types.+- New dashboard filters use declared attributes or scopes, at most two association hops deep. Prefer a `search` scope over a new `_or_` combination.+- Do not add an association list for the Seller audience; seller-facing filters on related data are scopes.+- An attribute exposed through `private_ransackable_attributes` for one audience must stay private in that audience's generated types. If a table shows otherwise, fix the declaration.++## Open Questions++None.++## References++- `spree/core/app/models/concerns/spree/ransackable_attributes.rb`: audience narrowing+- `spree/api/app/controllers/spree/api/v3/resource_controller.rb`: `collection`, `ransack_params`, prefixed ID and short-name decoding+- `packages/sdk-core/src/params.ts`: `transformListParams`+- `docs/plans/6.0-typed-preferences.md`: the same declarations-to-OpenAPI-to-SDK pipeline+- CLAUDE.md, "Typed values" (short-name filter values) and "Documentation" (specs generated from integration tests)diff --git a/docs/plans/decisions.md b/docs/plans/decisions.mdindex f2534b738f..91acee5767 100644--- a/docs/plans/decisions.md+++ b/docs/plans/decisions.md@@ -1,3 +1,13 @@+## 2026-10-09: Typed filters keep sellers association-free, take arrays for `_in`, and ship no 5.x warning++**Context:** List filters are being generated into OpenAPI and the SDKs from the Ransack allowlists, and PR C will reject unknown filters. Three choices fix what the published contract says before that happens.++**Decision:** The Seller API reaches no associations through filters, as today; related-data filters for sellers are scopes. `_in` and `_not_in` accept arrays only, never comma-separated strings. There is no 5.x deprecation release: the upgrade guide covers the change, and PR C adds a `Spree.api.strict_filters` setting (default on) that a store can turn off for one release.++**Consequences:** Seller SDK filter types stay attribute-only. A client sending `q[status_in]=a,b` gets a 400 once enforcement lands, which is the same empty result it already gets, made visible. Self-hosted stores learn of undeclared filters from the upgrade guide and the escape hatch, not from a warning in production.++**Plan:** `6.0-typed-filters.md`.+## 2026-10-09: Spree stops parsing numbers by locale**Context:** Price, variant, payment, refund, store credit, gift card and adjustment setters re-parsed every string with `Spree::LocalizedNumber` under the request's locale, for the legacy Rails admin. That admin is gone. In a store whose language writes a comma decimal (nl, de, fr) the setters read the dashboard's canonical `"49.50"` as 4950, and an untouched `"99.0"` grew tenfold on every save.