@spree/docs 0.1.240 → 0.1.242

package/dist/developer/customization/checkout.md

@@ -0,0 +1,117 @@
+---
+title: Customizing Checkout
+description: Add your own checkout step or requirement, and reorder or remove the built-in ones.
+---
+
+Spree does not run your checkout — your storefront does. What Spree owns is the list
+of things a cart still needs, which it reports on cart reads and enforces when you
+complete one. Adding to that list is how you make checkout require something of your
+own.
+
+> **NOTE:** For what a cart reports and how to read it, see
+>   [Carts](../core-concepts/carts.md#checkout-requirements). This page is about
+>   adding to it.
+
+## Requirements are the gate, steps are a label
+
+Two things are easy to confuse:
+
+- A **requirement** is enforced. It appears on cart reads while unmet, and completing
+  a cart recomputes the list and refuses if anything is outstanding.
+- A **step** is descriptive. It exists so a storefront can render a progress
+  indicator. Nothing on the server checks which step a customer is on.
+
+So a requirement is what you reach for when something must be true before an order
+exists. A step is only worth adding when your checkout genuinely has a stage the
+built-in five don't describe.
+
+## Adding a requirement
+
+When the flow is unchanged and you only need one more condition:
+
+```ruby server/config/initializers/spree.rb
+Spree::Checkout::Registry.add_requirement(
+  step: :address,
+  field: :vat_number,
+  message: 'VAT number is required for business orders',
+  satisfied: ->(cart) { cart.custom_fields['vat_number'].present? }
+)
+```
+
+While `satisfied:` returns false the cart reports the requirement and refuses to
+complete. Its `code` is derived as `<field>_required` — `vat_number_required` here.
+
+Pass `applicable:` to scope it. It is checked before `satisfied:`, so a requirement
+that doesn't apply never appears at all:
+
+```ruby
+applicable: ->(cart) { cart.customer&.company.present? }
+```
+
+`message` is stored verbatim — wrap it in `Spree.t` yourself if it needs translating.
+
+## Adding a step
+
+A step bundles its own requirements and says when it is satisfied:
+
+```ruby server/config/initializers/spree.rb
+Spree::Checkout::Registry.register_step(
+  name: :loyalty,
+  before: :payment,
+  satisfied: ->(cart) { cart.custom_fields['loyalty_number'].present? },
+  requirements: ->(cart) {
+    [{ step: 'loyalty', field: 'loyalty_number',
+       message: 'Loyalty number is required' }]
+  }
+)
+```
+
+The step now shows up in the cart's `current_step` and `completed_steps`, its
+requirements appear in `requirements` while unsatisfied, and completion refuses the
+cart until they are met.
+
+Each lambda receives the cart. Placement is controlled by two keywords:
+
+| Keyword | Effect |
+|---|---|
+| `before:` / `after:` | Place the step next to an existing one. `before:` wins if both are given |
+| `applicable:` | Whether the step exists for this cart at all — checked before `satisfied:` |
+
+An unanchored step lands immediately before `complete`. An anchor naming a step this
+particular cart doesn't have — `before: :payment` on a free cart — falls back to the
+same place.
+
+Unlike an added requirement, a step's `requirements:` lambda may set its own `code:`.
+
+## Reordering or removing built-in steps
+
+```ruby server/config/initializers/spree.rb
+# Drop a step from the reported list
+Spree::Checkout::Registry.base_steps.delete('confirm')
+
+# Or change when one applies
+Spree::Checkout::Registry.base_steps['payment'] = ->(cart) { cart.total > 0 }
+
+# Or reorder wholesale — known names keep their own applicability
+Spree::Checkout::Registry.base_step_names = %w[address payment delivery complete]
+```
+
+> **WARNING:** Removing a step removes it from the reported list. It does **not** remove the
+>   requirements filed under it — dropping `payment` does not let an unpaid cart
+>   complete. Requirements and steps are separate on purpose.
+
+## Prefer a requirement to a workflow hook
+
+A [workflow hook](workflows.md) on `carts.complete.validate`
+can also reject a cart, and there are cases for it — anything needing a network call, or a
+decision that only makes sense at the moment of completion.
+
+For anything a customer has to fix, a requirement is better: it is reported on every
+cart read, so the storefront can show it while they can still act, rather than failing
+at the last step with an error they have to interpret.
+
+## Related
+
+- [Carts](../core-concepts/carts.md) — reading requirements and completing a cart
+- [Custom fields](../core-concepts/metafields.md) — storing your own data on a cart
+- [Services & Workflows](workflows.md) — hooks that run during completion

package/dist/developer/customization/configuration.md

@@ -1,226 +1,127 @@
 ---
 title: Configuration
-description: Every global Spree setting that is actually read by Spree — grouped by area, with defaults and what each one changes.
+description: Every Spree setting, the environment variable that sets it, and what it changes.
 ---
 
-Global settings live in `config/initializers/spree.rb` and apply to the whole application. Anything that varies per store — currency, markets, delivery zones, languages — is data you change in the dashboard instead.
+All business configuration is done in the Admin Dashboard. What is left here is a
+small set of settings describing the *installation*: limits, expiries, and where
+things are hosted. **Every one of them is set with an environment
+variable**, so changing one is a config change rather than a code change.
 
-```ruby config/initializers/spree.rb
-Spree.config do |config|
-  config.minimum_password_length = 10
-  config.allow_empty_price_amount = true
-end
+```bash
+SPREE_MINIMUM_PASSWORD_LENGTH=10
+SPREE_JWT_EXPIRATION=1800
 ```
 
-> **NOTE:** Restart your Rails server after editing the initializer.
+Values are converted to the setting's type, so `SPREE_WEBHOOKS_ENABLED=false` really
+is false. A value that cannot be converted — `SPREE_JWT_EXPIRATION=abc` — fails at
+boot rather than silently reverting to the default.
 
-## Deployment settings read the environment
+> **NOTE:** Booleans accept `true`/`false`, `1`/`0`, `yes`/`no` and `on`/`off`, in any case.
 
-Settings that describe the deployment rather than commerce behavior can be set with an environment variable — no Ruby, no code change, no restart-after-edit dance. An explicitly configured value always wins over the environment.
+## Hosting
 
-| Setting | Environment variable | What it configures |
+| Variable | Default | What it does |
 |---|---|---|
-| `dashboard_url` | `SPREE_DASHBOARD_URL` | Origin where the admin dashboard is hosted (e.g. `https://admin.my-shop.com`). Used for every link that sends someone into the dashboard: invitation emails, SSO redirects, and the first-run setup link printed by `db:seed`. |
-| `seller_panel_url` | `SPREE_SELLER_PANEL_URL` | Origin where the marketplace seller panel is hosted, when you serve it somewhere other than this app's own `/sellers` mount. Used for links sent to sellers, today the invitation email. Leave it unset to use `/sellers`; with no panel deployed at all, those links open the dashboard. |
+| `SPREE_DASHBOARD_URL` | — | Origin where the dashboard is hosted. Used for every link that sends someone into it — invitation emails, SSO redirects, and the first-run setup link printed by `db:seed`. |
+| `SPREE_SELLER_PANEL_URL` | — | Origin where the marketplace seller panel is hosted, when it isn't this app's own `/sellers` mount. Unset uses `/sellers`; with no panel deployed, seller links open the dashboard. |
+| `SPREE_STORE_SCOPE_GUARD` | `log` | Tripwire for queries that miss a store scope, in development and test only. `log` warns, `raise` fails, `off` disables. Never active in production. |
 
-This page lists only settings Spree actually reads. Settings that exist for backwards compatibility are listed under [Deprecated settings](#deprecated-settings) rather than mixed in with the rest.
+## Carts
 
-## Settings that belong to a store
-
-Settings that shape how a shop sells — when customers are charged, whether stock is counted, which products appear without a price — are properties of a store, not of the installation, so they live on `Spree::Store` and are edited in the dashboard under **Settings → Store**:
-
-`capture_method`, `track_inventory_levels`, `stock_reservations_enabled`, `stock_reservation_ttl_minutes`, `track_price_history`, `show_products_without_price`, `disable_sku_validation`, `address_requires_phone`, `company_field_enabled`, `tax_using_ship_address`, plus `guest_checkout` and `storefront_access` — those last two are owned by the channel, and the store's value is what a channel falls back to.
-
-The global versions of these settings still exist but are no longer read, so setting one in the initializer changes nothing. If you're upgrading from an installation that used them, run `bin/rake spree:store_settings:backfill_from_config` to copy your values onto every store.
-
-```ruby
-store = Spree::Current.store
-store.preferred_capture_method                # => "checkout"
-store.update!(preferred_track_inventory_levels: false)
-```
-
-### When customers are charged
-
-`capture_method` says when a customer is charged rather than only authorized. It applies to every payment method, not just card gateways. It takes one of three values:
-
-| Value | What happens |
-|---|---|
-| `checkout` | The money is taken as soon as the order is placed. This is the default. |
-| `on_dispatch` | The amount is authorized at checkout and captured when the goods are dispatched. |
-| `manual` | The amount is authorized at checkout and staff capture it when they choose. |
-
-A payment method can override the store for its own payments by setting the same three values; leaving it blank inherits the store's choice. Ask a payment method what applies with `resolved_capture_method`, or use the `capture_at_checkout?`, `capture_on_dispatch?` and `capture_manually?` questions.
-
-```ruby
-payment_method.update!(capture_method: 'on_dispatch')
-payment_method.resolved_capture_method        # => "on_dispatch"
-
-payment_method.update!(capture_method: nil)   # back to inheriting
-payment_method.resolved_capture_method        # => "checkout"
-```
-
-If you're upgrading from an installation that used the older `auto_capture` and `auto_capture_on_dispatch` booleans, two tasks carry it over: `spree:store_settings:backfill_from_config` maps the old globals onto each store's `capture_method`, and `spree:migrate_capture_methods` converts the per-payment-method `auto_capture` column. A method left without a value inherits its store.
-
-## Checkout and payments
-
-| Setting | Default | What it does |
+| Variable | Default | What it does |
 |---|---|---|
-| `always_include_confirm_step` | `false` | Always shows a confirmation step, even when the payment method doesn't need one. |
-| `credit_to_new_allocation` | `false` | Records refunded store credit as a new entry each time instead of topping the original credit back up. |
+| `SPREE_GUEST_CART_EXPIRY_DAYS` | `30` | How long an abandoned guest cart is kept before deletion. |
+| `SPREE_CUSTOMER_CART_EXPIRY_DAYS` | `90` | How long a signed-in customer's abandoned cart is kept. |
+| `SPREE_EMPTY_CART_EXPIRY_HOURS` | `48` | How long a cart with no items is kept. |
 
-## Carts and stock reservations
+## Products and pricing
 
-| Setting | Default | What it does |
+| Variable | Default | What it does |
 |---|---|---|
-| `guest_cart_expiry_days` | `30` | How long an abandoned guest cart is kept before deletion. |
-| `customer_cart_expiry_days` | `90` | How long a signed-in customer's abandoned cart is kept. |
-| `empty_cart_expiry_hours` | `48` | How long a cart with no items is kept. |
+| `SPREE_ALLOW_EMPTY_PRICE_AMOUNT` | `false` | Allows a price to be left blank instead of requiring an amount. Prices in a price list already allow blank. |
+| `SPREE_ALWAYS_USE_TRANSLATIONS` | `false` | Always read product, category and collection names from the translation tables, even in the store's own default language. |
 
-## Products and pricing
+## Payments
 
-| Setting | Default | What it does |
+| Variable | Default | What it does |
 |---|---|---|
-| `allow_empty_price_amount` | `false` | Allows a price to be left blank instead of requiring an amount. Prices in a price list already allow blank. |
-| `price_history_retention_days` | `30` | How many days of price history the `spree:price_history:prune` task keeps. |
-| `always_use_translations` | `false` | Always read product, category and collection names from the translation tables, even in the store's own default language. |
+| `SPREE_CREDIT_TO_NEW_ALLOCATION` | `false` | Records refunded store credit as a new entry each time instead of topping the original credit back up. |
 
 ## Addresses
 
-| Setting | Default | What it does |
+| Variable | Default | What it does |
 |---|---|---|
-| `geocode_addresses` | `true` | Looks up latitude and longitude for saved addresses. |
+| `SPREE_GEOCODE_ADDRESSES` | `true` | Looks up latitude and longitude for saved addresses. |
 
-## Media
+## Uploads
 
-| Setting | Default | What it does |
+| Variable | Default | What it does |
 |---|---|---|
-| `max_image_download_size` | `20971520` | Largest file size, in bytes, accepted when downloading an image from an external URL. |
-| `images_save_from_url_job_attempts` | `5` | How many times to retry fetching an external image before giving up. |
+| `SPREE_MAX_IMAGE_DOWNLOAD_SIZE` | `20971520` | Largest file accepted when downloading an image from an external URL, in bytes (20 MB). |
+| `SPREE_IMAGES_SAVE_FROM_URL_JOB_ATTEMPTS` | `5` | How many times to retry fetching an external image before giving up. |
+| `SPREE_MAX_VIDEO_UPLOAD_SIZE` | `524288000` | Largest product video accepted, in bytes (500 MB). |
+| `SPREE_MAX_SELLER_DOCUMENT_UPLOAD_SIZE` | `20971520` | Largest document a seller may upload for a requirement, in bytes (20 MB). Small on purpose — these are certificates and registrations. |
 
 ## Promotions and gift cards
 
-| Setting | Default | What it does |
+| Variable | Default | What it does |
 |---|---|---|
-| `coupon_codes_web_limit` | `500` | How many coupon codes are created immediately when saving a promotion. Larger batches move to a background job so saving stays fast. |
-| `coupon_codes_total_limit` | `5000` | Maximum coupon codes a single promotion may generate. |
-| `gift_card_batch_web_limit` | `500` | How many gift card codes a batch creates immediately before switching to a background job. |
-| `gift_card_batch_limit` | `50000` | Maximum gift card codes in a single batch. |
+| `SPREE_COUPON_CODES_WEB_LIMIT` | `500` | How many coupon codes are created immediately when saving a promotion. Larger batches move to a background job so saving stays fast. |
+| `SPREE_COUPON_CODES_TOTAL_LIMIT` | `5000` | Maximum coupon codes a single promotion may generate. |
+| `SPREE_GIFT_CARD_BATCH_WEB_LIMIT` | `500` | How many gift card codes a batch creates immediately before switching to a background job. |
+| `SPREE_GIFT_CARD_BATCH_LIMIT` | `50000` | Maximum gift card codes in a single batch. |
 
 ## Accounts and passwords
 
-| Setting | Default | What it does |
+| Variable | Default | What it does |
 |---|---|---|
-| `minimum_password_length` | `8` | Shortest password a customer or staff member may set. |
-| `maximum_password_length` | `72` | Longest password allowed. |
-| `max_failed_login_attempts` | `5` | Failed sign-ins before an account is temporarily locked. |
-| `lockout_duration` | `1800` | How long an account stays locked, in seconds. |
-| `customer_password_reset_expires_in` | `15` | How long a customer's password reset link stays valid, in minutes. |
-| `admin_password_reset_expires_in` | `15` | How long a staff password reset link stays valid, in minutes. |
-
-## URLs
-
-| Setting | Default | What it does |
-|---|---|---|
-| `dashboard_url` | `nil` | Where the React dashboard lives, so single sign-on can send staff back to it after they authenticate. |
-| `admin_url` | `nil` | Base address used to build staff invitation links in email. Invitation links are relative when this is unset. |
+| `SPREE_MINIMUM_PASSWORD_LENGTH` | `8` | Shortest password a customer or staff member may set. |
+| `SPREE_MAXIMUM_PASSWORD_LENGTH` | `ActiveModel::SecurePassword::MAXPASSWORDLENGTHALLOWED` | Longest password allowed. |
+| `SPREE_MAX_FAILED_LOGIN_ATTEMPTS` | `5` | Failed sign-ins before an account is temporarily locked. |
+| `SPREE_LOCKOUT_DURATION` | `1800` | How long an account stays locked, in seconds. |
+| `SPREE_CUSTOMER_PASSWORD_RESET_EXPIRES_IN` | `15` | How long a customer's password reset link stays valid, in minutes. |
+| `SPREE_ADMIN_PASSWORD_RESET_EXPIRES_IN` | `15` | How long a staff password reset link stays valid, in minutes. |
 
 ## Imports and events
 
-| Setting | Default | What it does |
+| Variable | Default | What it does |
 |---|---|---|
-| `large_import_threshold` | `500` | Row count above which a CSV import switches to bulk processing — faster, with less live progress detail. |
-| `events_log_enabled` | `true` | Writes every Spree event to the Rails log. |
-| `disable_migration_check` | `false` | Silences the boot warning about pending engine migrations. |
-
-## API settings
+| `SPREE_LARGE_IMPORT_THRESHOLD` | `500` | Row count above which a CSV import switches to bulk processing — faster, with less live progress detail. |
+| `SPREE_EVENTS_LOG_ENABLED` | `true` | Writes every Spree event to the Rails log. |
+| `SPREE_DISABLE_MIGRATION_CHECK` | `false` | Silences the boot warning about pending engine migrations. |
 
-API settings live on their own configuration object:
+## API authentication
 
-```ruby config/initializers/spree.rb
-Spree::Api::Config.jwt_expiration = 1800
-```
-
-### Authentication
-
-| Setting | Default | What it does |
+| Variable | Default | What it does |
 |---|---|---|
-| `jwt_expiration` | `3600` | How long a customer or store access token stays valid, in seconds. |
-| `admin_jwt_expiration` | `300` | How long a staff access token stays valid. Deliberately short — admin tokens carry far more privilege. |
-| `refresh_token_expiry` | `2592000` | How long a refresh token stays valid, in seconds (30 days). |
-| `jwt_secret_key` | `nil` | Signing key for tokens. Falls back to the Rails secret key base. |
+| `SPREE_JWT_EXPIRATION` | `3600` | How long a customer or store access token stays valid, in seconds. |
+| `SPREE_ADMIN_JWT_EXPIRATION` | `300` | How long a staff access token stays valid. Deliberately short — staff tokens carry far more privilege. |
+| `SPREE_REFRESH_TOKEN_EXPIRY` | `2592000` | How long a refresh token stays valid, in seconds (30 days). |
+| `SPREE_JWT_SECRET_KEY` | — | Signing key for tokens. Falls back to `Rails.application.credentials.jwt_secret_key`, then the Rails secret key base. |
 
-### Rate limits
+## API rate limits
 
-| Setting | Default | What it does |
+| Variable | Default | What it does |
 |---|---|---|
-| `rate_limit_window` | `60` | Length of the rate-limit window, in seconds. |
-| `rate_limit_per_key` | `300` | Requests allowed per window for each publishable API key + client IP pair (per visitor), and for keyless traffic per IP. Applies across the whole API, not per endpoint. |
-| `rate_limit_per_secret_key` | `600` | Requests allowed per secret API key per window, across the whole API. |
-| `rate_limit_login` | `5` | Sign-in attempts allowed per IP per window. |
-| `rate_limit_register` | `3` | Registration attempts per IP. |
-| `rate_limit_refresh` | `10` | Token refresh attempts per IP. |
-| `rate_limit_password_reset` | `3` | Password reset requests per IP. |
-| `max_request_body_size` | `102400` | Largest accepted request body, in bytes (100 KB). |
-
-### Webhooks
-
-| Setting | Default | What it does |
+| `SPREE_RATE_LIMIT_WINDOW` | `60` | Length of the rate-limit window, in seconds. |
+| `SPREE_RATE_LIMIT_PER_KEY` | `300` | Requests per window for each publishable key + client IP pair, and for keyless traffic per IP. Across the whole API, not per endpoint. |
+| `SPREE_RATE_LIMIT_PER_SECRET_KEY` | `600` | Requests per secret API key per window, across the whole API. |
+| `SPREE_RATE_LIMIT_LOGIN` | `5` | Sign-in attempts allowed per IP per window. |
+| `SPREE_RATE_LIMIT_REGISTER` | `3` | Registration attempts per IP. |
+| `SPREE_RATE_LIMIT_REFRESH` | `10` | Token refresh attempts per IP. |
+| `SPREE_RATE_LIMIT_PASSWORD_RESET` | `3` | Password reset requests per IP. |
+| `SPREE_MAX_REQUEST_BODY_SIZE` | `102400` | Largest accepted request body, in bytes (100 KB). |
+
+## Webhooks
+
+| Variable | Default | What it does |
 |---|---|---|
-| `webhooks_enabled` | `true` | Whether webhooks fire at all. |
-| `webhooks_verify_ssl` | `true` | Verifies SSL certificates on webhook endpoints. Off in development. |
-
-## Reading a setting
-
-```ruby
-Spree::Config.minimum_password_length  # => 8
-Spree::Api::Config.jwt_expiration      # => 3600
-```
-
-Assigning at runtime affects only the current process and is lost on restart. Set values in the initializer to make them stick.
-
-## Deprecated settings
-
-These still exist so upgrades don't break, but Spree either ignores them or reads them only from subsystems it has replaced. Don't use them in new code.
-
-| Setting | Use instead |
-|---|---|
-| `return_eligibility_number_of_days` | The `return_window_days` preference on [Market](../core-concepts/markets.md), or a `returns.create.validate` [hook](workflows.md) |
-| `restock_inventory` | Restocking is decided per return line item by its resellable flag — see [Returns](../core-concepts/returns-exchanges-claims.md#processing-a-return) |
-| `expedited_exchanges` | [Exchanges](../core-concepts/returns-exchanges-claims.md) |
-| `expedited_exchanges_days_window` | [Exchanges](../core-concepts/returns-exchanges-claims.md) |
-| `enable_legacy_default_price` | Compatibility switch for the old default-price behavior; leave off |
-| `use_user_locale` | Locale comes from the `x-spree-locale` header or the `locale` parameter |
-| `company` | The `company_field_enabled` setting on the store |
-| `address_requires_phone` | The `address_requires_phone` setting on the store |
-| `default_stock_reservation_ttl_minutes` | The `stock_reservation_ttl_minutes` setting on the store |
-| `auto_capture` | The `capture_method` setting on the store |
-| `auto_capture_on_dispatch` | The `capture_method` setting on the store |
-| `stock_reservations_enabled` | The `stock_reservations_enabled` setting on the store |
-| `track_inventory_levels` | The `track_inventory_levels` setting on the store |
-| `show_products_without_price` | The `show_products_without_price` setting on the store |
-| `disable_sku_validation` | The `disable_sku_validation` setting on the store |
-| `track_price_history` | The `track_price_history` setting on the store |
-| `tax_using_ship_address` | The `tax_using_ship_address` setting on the store |
-| `disable_store_presence_validation` | Every store-owned record now requires a store |
-
-> **WARNING:** These settings have no effect at all, and are scheduled for removal: `allow_checkout_on_gateway_error` (completion checks whether payments cover the total, so a failed gateway call never completes an order), `products_per_page`, `alternative_shipping_phone`, `show_variant_full_price`, `reserve_stock_on`, `storefront_products_path`, `storefront_taxons_path`, `storefront_pages_path`. Setting them changes nothing.
-
-## Settings that have been removed
-
-These settings are gone. Assigning one in your initializer now raises `NoMethodError`, so delete the line.
-
-| Setting | What to do instead |
-|---|---|
-| `send_core_emails` | The `send_consumer_transactional_emails` setting on the store, which turns a shop's customer emails on and off. |
-| `currency` | Currency belongs to the store and the market. |
-| `address_requires_state` | State requirements come from the address country. |
-| `checkout_zone` | Use [delivery zones](../core-concepts/fulfillments.md#delivery-methods-and-zones). |
-| `allow_guest_checkout` | Use the `guest_checkout` setting on the store or channel. |
-| `binary_inventory_cache` | A stock change always touches its variant. |
-| `logo`, `mailer_logo` | The store's own `logo` and `mailer_logo` images, uploaded in the dashboard. Only the global settings are gone; the images themselves are unchanged. |
-| `layout`, `always_put_site_name_in_title`, `title_site_name_separator`, `max_level_in_taxons_menu`, `show_raw_product_description`, `shipping_instructions`, `show_only_complete_orders_by_default` | These configured the removed Rails storefront and admin. A storefront owns its own presentation. |
+| `SPREE_WEBHOOKS_ENABLED` | `true` | Whether webhooks fire at all. |
+| `SPREE_WEBHOOKS_VERIFY_SSL` | `true` | Verifies SSL certificates on webhook endpoints. Off in development. |
 
 ## Related
 
+- [Stores](../core-concepts/stores.md) — the settings a shop owns
 - [Model preferences](model-preferences.md) — per-record settings
 - [Services & Workflows](workflows.md) — changing behavior rather than settings