@spree/docs 0.1.157 → 0.1.159

package/dist/developer/customization/validations.md

@@ -0,0 +1,173 @@
+---
+title: Validations
+section: customization
+---
+
+## Overview
+
+Adding a rule — and occasionally relaxing one Spree ships — is one of the most
+common reasons to reach into core models. There are three ways to do it, and
+picking the right one is mostly a question of *what kind of rule* you have.
+
+| Your rule is about… | Use |
+|---|---|
+| Whether an **operation** may happen — a purchase limit, B2B eligibility, a region policy | A workflow [`validate` hook](workflows.md) |
+| The **shape of a record** — a field you added must be present, a format must match | A [decorator](decorators.md) adding a validation |
+| A **new attribute** you need on an existing model | [Custom fields](../core-concepts/metafields.md) |
+
+Spree deliberately has no registry for adding or removing arbitrary model
+validations. Adding one with a decorator is already a single line of ordinary
+Rails, and removing a core rule is served by the knobs below.
+
+## Vetoing an operation
+
+This is the one to reach for first. A `validate` hook runs inside the flow,
+before anything is written, and can stop it:
+
+```ruby
+# config/initializers/spree.rb
+Spree.hooks.register('carts.add_item.validate', 'MyStore::CheckPurchaseLimit')
+Spree.hooks.register('carts.upsert_items.validate', 'MyStore::CheckPurchaseLimit')
+
+module MyStore
+  class CheckPurchaseLimit
+    def call(workflow)
+      return if workflow.quantity <= 10
+
+      workflow.errors.add(:quantity, :purchase_limit_exceeded,
+                          message: 'You can order at most 10 of this item.')
+      workflow.reject!
+    end
+  end
+end
+```
+
+Why this beats a model validation for operational rules: it runs only for the
+operation you targeted, so a data migration or an admin correction isn't fought
+by a customer-facing rule; it sees the whole flow, not one record; and it can
+tell staff from customers (`workflow.created_by`) to allow a supervisor
+override.
+
+Both cart keys appear above because adding to a cart and setting a quantity are
+different flows. See [Services & Workflows](workflows.md)
+for the full hook list.
+
+## Adding a rule to a model
+
+For rules about the shape of a record, a decorator is the supported route:
+
+```ruby
+# app/models/spree/product_decorator.rb
+module MyStore
+  module ProductDecorator
+    def self.prepended(base)
+      base.validates :external_id, presence: true, uniqueness: true
+    end
+  end
+end
+
+Spree::Product.prepend(MyStore::ProductDecorator)
+```
+
+Decorators couple you to Spree internals, so prefer a hook when the rule is
+really about an operation. See
+[Decorators](decorators.md).
+
+## Relaxing a rule Spree ships
+
+Never call `clear_validators!` — it wipes every validation on the model,
+including ones added by other extensions, and the breakage appears far from the
+cause. Use one of these instead.
+
+### Store preferences
+
+Some rules are already switchable, per store, from the dashboard or a console:
+
+| Preference | Effect |
+|---|---|
+| `address_requires_phone` | Requires a phone number on addresses |
+| `company_field_enabled` | Shows the company field on address forms |
+| `address_requires_company` | Requires it — only meaningful with the field shown |
+| `disable_sku_validation` | Turns off SKU uniqueness |
+
+```ruby
+store.update!(preferred_address_requires_company: true)
+```
+
+### Overriding the gating predicate
+
+Most conditional validations in `Spree::Address` are gated on a predicate you
+can override, which is far safer than removing the validation:
+
+```ruby
+module MyStore
+  module AddressDecorator
+    # Business addresses only in this store.
+    def require_company?
+      !quick_checkout
+    end
+  end
+end
+
+Spree::Address.prepend(MyStore::AddressDecorator)
+```
+
+`require_name?`, `require_street?`, `require_zipcode?`, `require_phone?` and
+`require_company?` all work this way.
+
+### The address validator registry
+
+Address rules are regional and business-specific, so addresses carry a registry
+of extra validator classes you can add to and remove from:
+
+```ruby
+# config/initializers/spree.rb — or config.to_prepare for your own classes
+Spree.validators.addresses.register(MyStore::PostBoxValidator)
+
+# Drop a rule Spree ships
+Spree.validators.addresses.unregister(Spree::Addresses::PhoneValidator)
+```
+
+A validator is an ordinary `ActiveModel::Validator`:
+
+```ruby
+module MyStore
+  class PostBoxValidator < ActiveModel::Validator
+    def validate(record)
+      return unless record.address1.to_s.match?(/\A\s*P\.?O\.? Box/i)
+
+      record.errors.add(:address1, :po_box_not_deliverable)
+    end
+  end
+end
+```
+
+Register your own classes from `config.to_prepare` rather than an initializer —
+the registry holds classes, and a reloadable constant registered once at boot
+goes stale on the next reload.
+
+## Checkout requirements
+
+Rules about what a cart needs *before it can be completed* — a phone number
+before delivery, a purchase order number for B2B — belong in the checkout
+requirements registry rather than a model validation, because they also drive
+what the storefront shows as outstanding:
+
+```ruby
+Spree::Checkout::Registry.add_requirement(
+  step: 'address',
+  field: 'phone',
+  message: 'Phone number is required for delivery',
+  satisfied: ->(cart) { cart.ship_address&.phone.present? }
+)
+```
+
+See the [Spree 6 quickstart](/v6/developer/customization/quickstart) for the full registry API.
+
+## Custom field values
+
+Custom fields currently validate their type only — a `Number` field rejects
+non-numbers, a `Json` field rejects malformed JSON. There is no per-definition
+length, range or format rule yet. A product type marking a custom field as
+*required* is an advisory marker shown in the dashboard; the server does not
+enforce it.

package/dist/developer/customization/workflows.md

@@ -37,7 +37,7 @@ result = Spree.cart_add_item_workflow.call(cart: cart, variant: variant, quantit
 if result.success?
   line_item = result.value
 else
-  puts result.error.value
+  puts result.error.to_s
 end
 ```
 
@@ -76,12 +76,31 @@ module MyStore
       # every #perform keyword is a reader: cart, variant, quantity, ...
       return if workflow.quantity <= 10
 
-      workflow.reject!('You can order at most 10 of this item.')
+      workflow.errors.add(:quantity, :purchase_limit_exceeded,
+                          message: 'You can order at most 10 of this item.')
+      workflow.reject!
     end
   end
 end
 ```
 
+`workflow.errors` is an `ActiveModel::Errors`, the same object a model uses. A
+rejection therefore reaches the API in the shape clients already handle for
+validation failures — the field name, a symbolic code, and the message:
+
+```json
+{
+  "error": {
+    "code": "validation_error",
+    "message": "Quantity You can order at most 10 of this item.",
+    "details": { "quantity": ["You can order at most 10 of this item."] }
+  }
+}
+```
+
+Add to `:base` for a rejection that isn't about one field. `reject!('message')`
+with an argument is shorthand for exactly that.
+
 > **NOTE:** Hook keys are validated at boot. Registering against a hook that doesn't exist
 > raises `Spree::Hooks::UnknownHookError` with the list of valid hooks for that
 > workflow, so a typo fails immediately instead of silently never firing.
@@ -179,9 +198,10 @@ The caller receives a normal failure result — no exception reaches your
 controller:
 
 ```ruby
-result = Spree.cart_add_item_workflow.call(cart: cart, variant: variant)
+result = Spree.return_create_workflow.call(order: order, items: items)
 result.success?    # => false
-result.error.value # => "You can order at most 10 of this item."
+result.error.to_s  # => "This order is outside the 30-day return window."
+result.error.value # => ActiveModel::Errors — the rejection, field by field
 ```
 
 > **WARNING:** Reject from `validate` hooks, not from `after_*` hooks. Rejecting late still
@@ -227,6 +247,8 @@ is reported through `Rails.error` so it's visible rather than mysterious.
 |---|---|---|---|
 | `carts.add_item` | `validate` | validate | Before the line item is built |
 | `carts.add_item` | `after_item_added` | lifecycle | After the item is saved and totals recalculated (in transaction) |
+| `carts.upsert_items` | `validate` | validate | Once per item, immediately before that item is applied — quantity edits, removals and bulk payloads. Earlier items in the batch may already be written |
+| `carts.upsert_items` | `after_items_upserted` | lifecycle | After the batch is applied and the cart recalculated once (in transaction) |
 | `carts.complete` | `validate` | validate | After checkout requirements pass, before the order is created |
 | `carts.complete` | `before_finalize` | lifecycle | After payment, before the order is placed |
 | `carts.complete` | `after_finalize` | lifecycle | After the order is placed |
@@ -251,13 +273,33 @@ is reported through `Rails.error` so it's visible rather than mysterious.
 | `payments.handle_webhook` | `after_handle` | lifecycle | After the gateway callback is processed |
 | `customers.create` | `validate` | validate | After the customer is built, before it is saved — the registration-policy veto (bot screening, B2B approval) |
 | `customers.create` | `after_create` | lifecycle | After the customer is created and the newsletter subscriber linked |
+| `products.create` | `validate` | validate | After the product is built, before it is saved — fires for the Admin API, CSV imports and seeds alike |
+| `products.create` | `after_create` | lifecycle | After the product is saved (in transaction) |
+| `products.update` | `validate` | validate | With the pending attributes assigned, so `product.changes` describes the edit |
+| `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) |
 
 `before_cancel` and `before_resume` accept `reject!` like a `validate` hook.
 
 Draft-order editing in the admin uses **twin workflows** with their own keys —
-`orders.add_item`, `orders.recalculate`, `orders.recalculate_totals` — carrying
-the same hooks as their cart counterparts. Register against the cart key for
-storefront carts, the order key for admin edits, or both.
+`orders.add_item`, `orders.upsert_items`, `orders.recalculate`,
+`orders.recalculate_totals` — carrying the same hooks as their cart
+counterparts. Register against the cart key for storefront carts, the order key
+for admin edits, or both.
+
+> **NOTE:** `carts.add_item` **adds** to a quantity; `carts.upsert_items` **sets** it, and
+> is what a quantity edit, a removal (quantity `0`) and a bulk item payload all
+> run through. A rule about what may be in a cart therefore belongs on both keys —
+> the readers are the same (`cart`, `variant`, `quantity`), so one handler class
+> registers against each.
+> 
+> `upsert_items` is also the one flow where a rejection is **not** fatal on the
+> storefront: the vetoed item is skipped, the rest of the batch applies, and what
+> was dropped comes back in the cart's `warnings`. A customer restoring a saved
+> cart keeps whatever is still purchasable. Admin order edits behave the opposite
+> way — the whole edit fails — because a silently dropped row is worse than a
+> failed request when a merchant is editing.
 
 Inspect what's available at runtime:
 
@@ -340,7 +382,7 @@ The whole vocabulary:
 | `on_flow_failure: :name` | Names the undo for a step, run in reverse if a later step fails |
 | `run_hooks :name` | Dispatches a declared hook; returns the merged hash from context handlers |
 | `failure(value, error)` | Aborts the flow — rolls back an open transaction and returns a failure result |
-| `reject!(message)` | The same, named for hook handlers vetoing a flow |
+| `reject!` | The same, named for hook handlers vetoing a flow — carries `workflow.errors` |
 | `halt!(value)` | Successful early exit (not valid inside a transaction the workflow opened) |
 | `hooks :a, :b` | Declares the extension points this workflow dispatches |
 

package/dist/developer/deployment/telemetry.md

@@ -0,0 +1,218 @@
+---
+title: Telemetry
+description: Distributed tracing with OpenTelemetry — one gem, standard OTEL_* environment variables, and every checkout becomes a trace from HTTP request to gateway call to webhook delivery.
+---
+
+Spree supports [OpenTelemetry](https://opentelemetry.io), the open standard for
+distributed tracing. Install the optional `spree_opentelemetry` gem, point it
+at your collector with the same environment variables every other
+OpenTelemetry service uses, and Spree exports traces — no code changes, no
+vendor lock-in. Traces flow to any OpenTelemetry-compatible backend: Grafana
+Tempo, Jaeger, Datadog, Honeycomb, New Relic, Dynatrace, and others.
+
+## Setup
+
+Add the gem to your application's Gemfile:
+
+```ruby
+gem 'spree_opentelemetry'
+```
+
+Then configure the exporter through the standard OpenTelemetry environment
+variables:
+
+```bash
+OTEL_SERVICE_NAME=spree
+OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318
+```
+
+That is the entire setup. Without an exporter configured, the gem stays
+dormant and adds no overhead. `OTEL_SDK_DISABLED=true` turns telemetry off
+regardless of any other setting.
+
+Other standard variables work as documented in the
+[OpenTelemetry SDK configuration reference](https://opentelemetry.io/docs/languages/sdk-configuration/),
+including sampling:
+
+```bash
+# Sample 10% of traces (children follow their parent's decision)
+OTEL_TRACES_SAMPLER=parentbased_traceidratio
+OTEL_TRACES_SAMPLER_ARG=0.1
+```
+
+## What gets traced
+
+Two layers combine into one trace per request or job.
+
+**Framework spans** come from the official Rails auto-instrumentation: HTTP
+requests, controller actions, database queries, background job enqueues and
+executions, mail deliveries, and outbound HTTP calls. Trace context carries
+across the job boundary, so work that happens in a background job stays
+connected to the request that caused it.
+
+**Commerce spans** come from Spree itself:
+
+| Span | Kind | What it covers |
+|---|---|---|
+| `carts.complete` (any workflow key) | internal | One span per workflow run, with its outcome |
+| `carts.complete process_payments` (any step) | internal / client | One span per workflow step; steps declared as external I/O become client spans |
+| `carts.add_item hooks validate` | internal | Extension hook dispatch, only when handlers are registered |
+| `order.placed dispatch` | internal | Event delivery to each subscriber, showing whether it ran inline or was enqueued |
+| `spree.webhook.deliver order.placed` | client | Each webhook POST, with the destination host and response code |
+| `spree.gateway.purchase` (any gateway action) | client | Each payment gateway call — authorize, purchase, capture, void, credit, and payment session operations |
+
+A completed checkout, for example, produces one trace containing the HTTP
+request, the `carts.complete` workflow and its steps, the payment gateway
+call, the database work, and — linked from it — the background jobs and
+webhook deliveries the order triggered.
+
+Spree also propagates
+[W3C Trace Context](https://www.w3.org/TR/trace-context/) headers on outbound
+webhooks, so a system receiving your webhooks can join its own spans to the
+trace that produced the event.
+
+## Span attributes and personal data
+
+Span attributes never contain personal or sensitive data. They are limited to
+workflow and step names, gateway action names, payment method class names,
+event names, webhook destination hosts, and HTTP status codes. Order contents,
+customer emails, addresses, payment details, and webhook payloads are never
+attached to spans.
+
+## Metrics
+
+Spree exports the trace signal. Request rates, error rates, and latency
+percentiles per endpoint, workflow, or gateway are derived from spans in the
+OpenTelemetry Collector with the
+[span metrics connector](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/connector/spanmetricsconnector):
+
+```yaml
+# otel-collector config
+connectors:
+  spanmetrics:
+    dimensions:
+      - name: spree.workflow
+      - name: spree.gateway.action
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      exporters: [spanmetrics, otlp]
+    metrics:
+      receivers: [spanmetrics]
+      exporters: [prometheusremotewrite]
+```
+
+## Using with Sentry
+
+Sentry and OpenTelemetry are complementary — Sentry's error capture works
+independently of tracing, so having both installed (as spree-starter does)
+requires no special setup. For traces there are three arrangements:
+
+**Sentry for errors, OpenTelemetry for traces (default).** Nothing to
+configure. Just don't *also* enable Sentry's own performance tracing
+(`traces_sample_rate`) — that would instrument every request twice and
+produce two disconnected trace systems.
+
+**Sentry as the trace backend.** Sentry ingests OpenTelemetry spans directly
+through its [OTLP integration](https://docs.sentry.io/platforms/ruby/guides/rails/integrations/otlp/).
+Order matters here: Sentry registers its span processor inside `Sentry.init`,
+which only works if the OpenTelemetry SDK is already installed — so install
+Spree's telemetry explicitly at the top of the same initializer:
+
+```ruby
+# Gemfile
+gem 'sentry-opentelemetry'
+
+# config/initializers/sentry.rb
+SpreeOpenTelemetry.configure { |config| config.enabled = true }
+SpreeOpenTelemetry.install!
+
+Sentry.init do |config|
+  config.dsn = ENV['SENTRY_DSN']
+  config.otlp.enabled = true
+  # Do not set traces_sample_rate or instrumenter — OpenTelemetry owns tracing.
+end
+```
+
+```bash
+# Sentry provides the exporter (derived from the DSN) — tell the SDK not to
+# wire its own default OTLP exporter alongside it.
+OTEL_TRACES_EXPORTER=none
+```
+
+A DSN alone does **not** enable tracing; `config.otlp.enabled` is the
+explicit opt-in (Sentry bills for ingested spans, so error capture never
+silently becomes span ingestion).
+
+Spree's commerce spans — workflows, gateway calls, webhook deliveries — show
+up in Sentry's trace view, and Sentry errors are linked automatically to the
+span that was active when they were captured.
+
+**Both, via the collector.** Point Spree at an OpenTelemetry Collector and
+fan out from there — one pipeline exporting to your tracing backend and
+another to Sentry's OTLP endpoint. This is the most flexible arrangement for
+teams that want Grafana/Jaeger for latency work and Sentry for error triage
+over the same traces.
+
+## Correlating logs
+
+To connect log lines to traces, tag your Rails logs with the current trace:
+
+```ruby
+# config/environments/production.rb
+config.log_tags = [
+  ->(_request) { "trace_id=#{OpenTelemetry::Trace.current_span.context.hex_trace_id}" }
+]
+```
+
+## Trying it locally
+
+Run Jaeger with an OTLP receiver and point Spree at it:
+
+```bash
+docker run --rm -p 16686:16686 -p 4318:4318 jaegertracing/jaeger:latest
+```
+
+```bash
+OTEL_SERVICE_NAME=spree \
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
+bin/rails server
+```
+
+Place a test order and open [http://localhost:16686](http://localhost:16686)
+to see the trace.
+
+## Code-level configuration
+
+Everything routine is controlled by environment variables. A
+`SpreeOpenTelemetry.configure` block exists for the rest — adding
+instrumentation for libraries your app uses, removing a default, or advanced
+SDK tuning:
+
+```ruby
+# config/initializers/opentelemetry.rb
+SpreeOpenTelemetry.configure do |config|
+  config.use 'OpenTelemetry::Instrumentation::Redis'          # add an instrumentation
+  config.skip 'OpenTelemetry::Instrumentation::ActionMailer'  # remove a default
+  config.with_sdk { |otel| otel.add_span_processor(my_processor) }
+end
+```
+
+## Instrumenting your own code
+
+Spree's spans are built on `ActiveSupport::Notifications`, and yours can be
+too — or use the OpenTelemetry API directly:
+
+```ruby
+tracer = OpenTelemetry.tracer_provider.tracer('my_app')
+
+tracer.in_span('loyalty.award_points', attributes: { 'loyalty.points' => 50 }) do
+  # your code
+end
+```
+
+Custom workflows get traced automatically: every `Spree::Workflow` run, step,
+and hook dispatch is instrumented by the framework, including workflows your
+application or extensions define.

package/package.json

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