@spree/docs 0.1.168 → 0.1.170

package/dist/developer/customization/workflows.md

@@ -279,6 +279,40 @@ is reported through `Rails.error` so it's visible rather than mysterious.
 | `products.update` | `after_update` | lifecycle | After the product is saved (in transaction) |
 | `products.destroy` | `validate` | validate | Before the product is soft-deleted — refuse a deletion your store shouldn't allow |
 | `products.destroy` | `after_destroy` | lifecycle | After the soft-delete, for host cleanup (in transaction) |
+| `products.activate` | `validate` | validate | Before the product goes on sale — the place to require an image, a price or a category |
+| `products.activate` | `after_activate` | lifecycle | After the status is written (in transaction) |
+| `products.archive` | `validate` | validate | Before the product is taken off sale |
+| `products.archive` | `after_archive` | lifecycle | After the status is written (in transaction) |
+| `products.draft` | `validate` | validate | Before the product returns to draft |
+| `products.draft` | `after_draft` | lifecycle | After the status is written (in transaction) |
+| `gift_cards.apply` | `validate` | validate | Before a card is drawn against — who may spend a card, on what, up to how much |
+| `gift_cards.apply` | `after_apply` | lifecycle | After the store credit and payment exist (in transaction) |
+| `gift_cards.remove` | `validate` | validate | Before a card is taken back off an order |
+| `gift_cards.remove` | `after_remove` | lifecycle | After the balance is returned to the card (in transaction) |
+| `gift_cards.redeem` | `validate` | validate | Before the card is recorded as spent |
+| `gift_cards.redeem` | `after_redeem` | lifecycle | After the status is written (in transaction) |
+| `gift_cards.cancel` | `validate` | validate | Before a card is voided |
+| `gift_cards.cancel` | `after_cancel` | lifecycle | After the card is voided (in transaction) |
+| `price_lists.create` | `validate` | validate | After the list is built, before it is saved |
+| `price_lists.create` | `after_create` | lifecycle | After the list and its product membership exist (in transaction) |
+| `price_lists.update` | `validate` | validate | With the pending attributes assigned, before anything is written |
+| `price_lists.update` | `after_update` | lifecycle | After membership and price overrides are applied (in transaction) |
+| `price_lists.activate` | `validate` | validate | Before a price list takes effect |
+| `price_lists.activate` | `after_activate` | lifecycle | After the list goes live or is scheduled (in transaction) |
+| `price_lists.deactivate` | `validate` | validate | Before a price list stops applying |
+| `price_lists.deactivate` | `after_deactivate` | lifecycle | After the list is switched off (in transaction) |
+| `invitations.accept` | `validate` | validate | After the expiry and invitee checks pass, before any access is granted |
+| `invitations.accept` | `after_accept` | lifecycle | After the role is granted and the invitation marked accepted (in transaction) |
+| `imports.start_mapping` | `validate` | validate | Before the uploaded file is read |
+| `imports.start_mapping` | `after_start_mapping` | lifecycle | After the column mappings are built (in transaction) |
+| `imports.complete_mapping` | `validate` | validate | Before the mapping is accepted — refuse a mapping your store considers incomplete |
+| `imports.complete_mapping` | `after_complete_mapping` | lifecycle | After the mapping is accepted, before row creation is dispatched (in transaction) |
+| `imports.start_processing` | `validate` | validate | Before the import starts working through its rows |
+| `imports.start_processing` | `after_start_processing` | lifecycle | After the status is written (in transaction) |
+| `imports.complete` | `validate` | validate | Before the import is closed out |
+| `imports.complete` | `after_complete` | lifecycle | After the import is completed and the store touched (in transaction) |
+| `imports.retry_failed_rows` | `validate` | validate | Before failed rows are queued again |
+| `imports.retry_failed_rows` | `after_retry` | lifecycle | After the import returns to processing, before re-dispatch (in transaction) |
 
 `before_cancel` and `before_resume` accept `reject!` like a `validate` hook.
 
@@ -396,11 +430,66 @@ Two rules worth internalising:
 connection open across a network round trip, and a timeout leaves your database
 and the payment processor disagreeing about what happened.
 
-**New models get a plain `status` string, not a state machine.** Transitions are
+**Models get a plain `status` string, not a state machine.** Transitions are
 workflows: `MyStore::Subscriptions::Cancel.call(...)`, not `subscription.cancel!`.
 Transition callbacks hide side effects inside a save, cannot take arguments, and
 have no compensation story.
 
+As of 6.0 this is not just advice for new models — Spree has no state machines
+left. Every status a record can hold is declared with `Spree::HasStatus`, and
+every move between two of them is a workflow you can hook.
+
+## Statuses
+
+`Spree::HasStatus` declares the statuses a model can hold:
+
+```ruby
+class MyStore::Subscription < Spree.base_class
+  include Spree::HasStatus
+  has_status :trialing, :active, :paused, :canceled, default: :trialing
+end
+```
+
+That gives you an inclusion validation, a predicate per value
+(`subscription.paused?`), a scope per value (`Subscription.paused`) and
+`with_status(:active, :trialing)` for several at once. It deliberately does
+*not* give you a transition graph — deciding which moves are legal is the
+workflow's job, which is what lets a transition take arguments, call out to a
+gateway outside a transaction, and undo itself when a later step fails.
+
+Statuses are additive, so an extension can add its own without reopening the
+model:
+
+```ruby
+Spree::GiftCard.add_status(:on_hold, after: :active)
+```
+
+A custom status needs a custom workflow to move records into it. That is the
+design, not a gap: a central place validating transitions would be a state
+machine again.
+
+> **NOTE:** `has_status` never overwrites something the model already defines. Where a
+> status name means more than the column value — `Spree::GiftCard#active?` also
+> requires the card not to have expired, and `Spree::GiftCard.active` includes
+> partially redeemed cards — the model's own definition wins and the generated
+> one is skipped.
+
+### Moving a record between statuses
+
+Call the workflow, not the model:
+
+```ruby
+result = Spree.product_archive_workflow.call(product: product)
+result.success?
+```
+
+Spree ships one workflow per transition — `Spree::Products::Activate`,
+`Spree::GiftCards::Redeem`, `Spree::Imports::Complete`, and so on — each with
+its own `validate` and `after_*` hooks, all in
+[Available hooks](#available-hooks) above. Because the write and the event it
+publishes happen in the same place, registering against a hook is enough to
+see every transition, wherever it was triggered from.
+
 ## Observability
 
 Every step emits an `ActiveSupport::Notifications` event, so your APM sees the

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

@@ -384,10 +384,121 @@ The `compare_at_price` **reader** (which resolves against `cost_currency`) is un
 Also note:
 
 - **Ransack:** `default_price` is no longer a searchable association on `Variant`; query `prices` instead.
-- **`Spree::PermittedAttributes`:** the dead `:price` and `:compare_at_price` entries are dropped from `product_attributes` and `variant_attributes`. Prices were already written as nested `prices: [{ amount:, currency: }]` under variants — the top-level keys had no writer behind them.
+- **Prices in permitted params:** the dead `:price` and `:compare_at_price` entries are gone. Prices were already written as nested `prices: [{ amount:, currency: }]` under variants — the top-level keys had no writer behind them. (`Spree::PermittedAttributes` itself is removed in 6.0 — see below.)
 - Localized number parsing still happens: `Spree::Price#amount=` runs `Spree::LocalizedNumber.parse`, so `set_price(currency, '1,599.99')` works as `price=` did.
 - The variant validation that inferred a missing price from the product's default variant is gone. Set prices explicitly (the product and variant factories already do).
 
+### `Spree::PermittedAttributes` is removed
+
+The global permitted-attributes registry is gone, with no deprecation bridge. It
+existed so the Rails admin and storefront could share one allowlist; both are
+removed in 6.0, and API v3 declares its attributes in the controller.
+
+Removed alongside it: `Spree::Core::ControllerHelpers::StrongParameters` (the
+`permitted_*_attributes` helper methods it mixed into controllers) and the
+fallback that inferred an attribute list from the model name.
+
+Attributes you pushed from an initializer are now declared on the model, and
+standard resource endpoints append them to their own allowlist — so one
+declaration still covers the model's create and update endpoints.
+
+#### How to migrate
+
+**1. Find every call site.** The constant and the helper methods are both gone,
+so a missed reference raises `NameError` or `NoMethodError` the first time that
+code runs — loudly, but not necessarily at boot:
+
+```bash
+grep -rn "PermittedAttributes" app config lib
+grep -rnE "permitted_[[:alnum:]_]+_attributes" app config lib
+```
+
+The second pattern is deliberately broad: the helper module generated one
+`permitted_*_attributes` method per registry key, so there were dozens of them.
+
+**2. Decide what each attribute actually is.** Most fall into one of three
+buckets, and only the last needs this hook:
+
+| What you were adding | Where it goes in 6.0 |
+| --- | --- |
+| A merchant-managed field (text, number, dropdown) | [Custom Fields](../core-concepts/custom-fields.md) — no code, and filterable/sortable |
+| Config for an STI type you register (promotion rule, delivery method rule, …) | `additional_permitted_attributes` on that subclass, as before — unchanged |
+| A real database column your extension added to a core model | `additional_permitted_attributes` on the model |
+
+**3. Point each declaration at the model.** It stays in your initializer — only
+the receiver changes, from the global registry to the model itself:
+
+```ruby config/initializers/spree.rb
+# Before
+Spree::PermittedAttributes.product_attributes << :brand_id
+
+# After
+Spree::Product.additional_permitted_attributes += [:brand_id]
+```
+
+Use `+=`, not `=` — the list is per model, and assigning replaces whatever
+another extension already added. `<<` raises a `FrozenError`: the default is a
+frozen shared array, so mutating it in place would leak your attribute onto every
+other model.
+
+Declare only attributes of your own. Redeclaring a key the controller already
+permits (`metadata`, `prices`) does not widen it — strong parameters keeps the
+last filter for that key, so the controller's own would be replaced by yours.
+
+Entries are `params.permit` fragments, so collections and nested structures keep
+the shapes you already know: `[:brand_id, { region_ids: [] }]`.
+
+**4. Fix your own controllers.** If you subclassed a Spree v3 resource
+controller and relied on the attribute list being inferred from the model name,
+declare it now:
+
+```ruby
+class BrandsController < Spree::Api::V3::Admin::ResourceController
+  protected
+
+  def model_class
+    Spree::Brand
+  end
+
+  # Before: no such method — the base class inferred `brand_attributes`
+  # from the model name. Now you say what you accept.
+  def resource_permitted_attributes
+    [:name, :slug, :description]
+  end
+end
+```
+
+Declaring neither `resource_permitted_attributes` nor `permitted_params` raises
+`NotImplementedError` on the first write, so this surfaces in your test suite
+rather than silently permitting a stale list.
+
+**5. Verify a write actually persists.** A declaration that never reaches a
+controller fails silently — strong parameters drop the unpermitted key, the
+request still returns 200, and the column keeps its old value. Assert on the
+saved record, not the response status:
+
+```ruby
+patch "/api/v3/admin/products/#{product.prefixed_id}",
+      params: { brand_id: brand.id }, headers: headers
+
+expect(product.reload.brand_id).to eq(brand.id)
+```
+
+If that assertion fails, the endpoint is not consulting your declaration. Check
+whether the controller overrides `permitted_attributes` — that method is where
+the extension attributes are appended, so overriding it replaces them. Override
+`resource_permitted_attributes` instead.
+
+> **WARNING:** Two endpoints deliberately ignore the hook because their parameters are
+>   authorization data rather than resource data: API keys (`scopes`, `key_type`)
+>   and invitations (`role_id`). Adding attributes there needs a controller
+>   decorator, not a model declaration.
+
+STI types registered through a Spree registry (promotion rules and actions,
+delivery method rules, commission rules) already used
+`additional_permitted_attributes` and need no changes — the hook simply moved up
+to `Spree::Base`.
+
 ### `StateChange` and `LogEntry` are gone
 
 `Spree::StateChange` and `Spree::LogEntry` are removed — the models, the `state_changes` associations on `Order`, `Payment` and `Fulfillment`, the `log_entries` associations on `Payment` and `Refund`, and everything that wrote to them. Both were write-only: nothing in Spree read the rows back, and the admin screens that displayed them are gone.

package/package.json

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