@spree/docs 0.1.177 → 0.1.178

package/dist/developer/core-concepts/users.md

@@ -1,303 +0,0 @@
----
-title: Users
-description: How Spree models customer and admin users — Devise authentication, account data, roles, abilities, and access permissions across stores.
----
-
-## Overview
-
-Spree has two separate user types:
-
-- **Customers** — users who browse your store, manage their account, and purchase products via the Store API
-- **Admins** — users who manage the store via the Admin Panel
-
-| User type | Class | Default |
-|-----------|-------|---------|
-| Customers | `Spree.user_class` | `Spree::User` |
-| Admins | `Spree.admin_user_class` | `Spree::AdminUser` |
-
-> **INFO:** You can use your own user classes. See the [Customize Authentication guide](../customization/authentication.md) for details.
-
-## Customers
-
-Customers interact with your store through the Store API. They can register, log in, manage their profile, and view order history.
-
-```mermaid
-erDiagram
-    Customer ||--o{ Order : "places"
-    Customer ||--o{ Address : "has many"
-    Customer ||--o{ Wishlist : "has many"
-    Customer ||--o{ StoreCredit : "has many"
-    Customer ||--o{ PaymentSource : "has many"
-
-    Customer {
-        string id
-        string email
-        string first_name
-        string last_name
-    }
-
-    Order {
-        string number
-        string state
-    }
-
-    Address {
-        string firstname
-        string lastname
-        string address1
-        string city
-    }
-
-    Wishlist {
-        string name
-        boolean is_default
-    }
-```
-
-### Registration
-
-
-```typescript Store SDK
-const { token, user } = await client.customers.create({
-  email: 'john@example.com',
-  password: 'password123',
-  password_confirmation: 'password123',
-  first_name: 'John',
-  last_name: 'Doe',
-})
-// token => JWT token for subsequent authenticated requests
-// user => { id: "usr_xxx", email: "john@example.com", first_name: "John", ... }
-```
-
-```bash cURL
-curl -X POST 'https://api.mystore.com/api/v3/store/customers' \
-  -H 'X-Spree-Api-Key: pk_xxx' \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "email": "john@example.com",
-    "password": "password123",
-    "password_confirmation": "password123",
-    "first_name": "John",
-    "last_name": "Doe"
-  }'
-```
-
-
-### Login
-
-
-```typescript Store SDK
-const { token, user } = await client.auth.login({
-  email: 'john@example.com',
-  password: 'password123',
-})
-// Use the token for authenticated requests
-```
-
-```bash cURL
-curl -X POST 'https://api.mystore.com/api/v3/store/auth/login' \
-  -H 'X-Spree-API-Key: pk_xxx' \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "email": "john@example.com",
-    "password": "password123"
-  }'
-```
-
-
-The response includes a [JWT token](../../api-reference/store-api/authentication.md) and a `user` object. Pass the token in subsequent requests via the `Authorization: Bearer <token>` header. See the [account SDK guide](../sdk/store/account.md) for the full `auth.login`, refresh, and profile flows.
-
-### Token Refresh
-
-Refresh an expiring token to keep the session alive:
-
-
-```typescript Store SDK
-const { token } = await client.auth.refresh({
-  refresh_token: existingRefreshToken,
-})
-```
-
-```bash cURL
-curl -X POST 'https://api.mystore.com/api/v3/store/auth/refresh' \
-  -H 'X-Spree-API-Key: pk_xxx' \
-  -H 'Content-Type: application/json' \
-  -d '{ "refresh_token": "rt_xxx" }'
-```
-
-
-### Customer Profile
-
-
-```typescript Store SDK
-// Get current customer
-const customer = await client.customer.get()
-// {
-//   id: "usr_xxx",
-//   email: "john@example.com",
-//   first_name: "John",
-//   last_name: "Doe",
-//   default_shipping_address: { ... },
-//   default_billing_address: { ... },
-//   addresses: [{ ... }, { ... }],
-// }
-
-// Update profile
-const updated = await client.customer.update({
-  first_name: 'Jonathan',
-  accepts_email_marketing: true,
-})
-```
-
-```bash cURL
-# Get current customer
-curl 'https://api.mystore.com/api/v3/store/customers/me' \
-  -H 'Authorization: Bearer <jwt_token>'
-
-# Update profile
-curl -X PATCH 'https://api.mystore.com/api/v3/store/customers/me' \
-  -H 'Authorization: Bearer <jwt_token>' \
-  -H 'Content-Type: application/json' \
-  -d '{ "first_name": "Jonathan", "accepts_email_marketing": true }'
-```
-
-
-### Customer Resources
-
-Authenticated customers have access to these resources:
-
-| Resource | Description |
-|----------|-------------|
-| [**Addresses**](addresses.md#customer-address-book) | Billing and shipping addresses with default selection |
-| [**Orders**](orders.md#order-history) | Past order history |
-| **Credit Cards** | Saved credit cards for checkout |
-| **Payment Sources** | Other saved payment methods (PayPal, Klarna, etc.) |
-| **Store Credits** | Balance assigned by the store, usable at checkout |
-| **Gift Cards** | Gift cards owned by or assigned to the customer |
-| **Wishlists** | Saved product lists |
-
-### Guest Checkout
-
-Customers don't need to register to purchase. Guest checkout uses an order token (`X-Spree-Token`) to identify the cart. See [Orders — Cart](orders.md#cart) for details.
-
-## Admin Users
-
-Admin users manage the store via the Admin Panel. They have roles that control what they can access.
-
-```mermaid
-erDiagram
-    AdminUser ||--o{ RoleUser : "has many"
-    RoleUser }o--|| Role : "belongs to"
-    RoleUser }o--|| Store : "scoped to"
-    AdminUser ||--o{ Invitation : "invites"
-
-    AdminUser {
-        string id
-        string email
-    }
-
-    RoleUser {
-        string role_id
-        string resource_type
-        string resource_id
-    }
-
-    Role {
-        string name
-    }
-
-    Invitation {
-        string email
-        string status
-        string token
-        datetime expires_at
-    }
-```
-
-### Roles
-
-Admin users can have different roles that control their permissions:
-
-| Role | Description |
-|------|-------------|
-| `admin` | Full access to all Admin Panel features |
-
-> **INFO:** You can create custom roles with specific permissions. See the [Customize Permissions guide](../customization/permissions.md) for details.
-
-### Creating Admin Users
-
-Use the Spree CLI to create admin users:
-
-```bash
-spree user create
-```
-
-The CLI will prompt you for the email and password. You can also pass them directly:
-
-```bash
-spree user create --email admin@example.com --password secret123
-```
-
-The created user gets the `admin` role on the default store.
-
-### Inviting Admin Users
-
-You can invite new admins through the Admin Panel or programmatically.
-
-**Via Admin Panel:**
-
-1. Navigate to **Settings → Users**
-2. Click **Invite User**
-3. Enter the email address and select a role
-4. Click **Send Invitation**
-
-The invitee receives an email with an invitation link. If they already have an account, they log in to accept. Otherwise, they create an account first.
-
-```mermaid
-flowchart TB
-    A[Admin creates invitation] --> B[Invitation email sent]
-    B --> C[Invitee clicks link]
-    C --> D{Has account?}
-    D -->|Yes| E[Log in]
-    D -->|No| F[Create account]
-    E --> G[Accept invitation]
-    F --> G
-    G --> H[Role assigned to store]
-```
-
-#### Invitation Details
-
-| Attribute | Description |
-|-----------|-------------|
-| `email` | Invitee's email address |
-| `token` | Secure token for the invitation link |
-| `status` | `pending` or `accepted` |
-| `expires_at` | Expiration date (default: 2 weeks) |
-| `resource` | The store being granted access to |
-| `role` | The role to assign upon acceptance |
-
-#### Invitation Events
-
-The invitation system publishes [events](events.md) you can subscribe to:
-
-| Event | Description |
-|-------|-------------|
-| `invitation.created` | Invitation was created (triggers email) |
-| `invitation.accepted` | Invitation was accepted and role assigned |
-| `invitation.resent` | Invitation was resent to the invitee |
-
-## Permissions
-
-Spree uses [CanCanCan](https://github.com/CanCanCommunity/cancancan) for authorization. Permissions apply to both customers (Store API access) and admins (Admin Panel access).
-
-See the [Customize Permissions guide](../customization/permissions.md) for details on creating custom roles and permission sets.
-
-## Related Documentation
-
-- [Addresses](addresses.md) — Customer address management
-- [Orders](orders.md) — Order history and checkout
-- [Authentication](../customization/authentication.md) — Custom authentication setup
-- [Permissions](../customization/permissions.md) — Roles and authorization
-- [Events](events.md) — Subscribe to user and invitation events
-- [Store API Authentication](../../api-reference/store-api/authentication.md) — Customer JWT auth flow
-- [Admin API Authentication](../../api-reference/admin-api/authentication.md) — Staff JWT + scopes auth flow

package/dist/developer/customization/authentication.md

@@ -1,100 +0,0 @@
----
-title: Authentication
-description: Integrate Spree with a custom authentication setup, including Devise, an existing user model, OmniAuth providers, and JWT or OAuth API tokens.
-version: v5
----
-
-If you installed Spree following the [Quickstart guide](../quickstart.md), you can completely skip this step - you are all set and integrated with the [Devise](https://github.com/plataformatec/devise) gem.
-
-However if you're adding Spree to an existing application that has its own authentication system, you will need to follow these steps.
-
-## Using Devise
-
-If you're currently using [Devise](https://github.com/plataformatec/devise) for authentication, you can follow the steps below to integrate Spree with your existing authentication system.
-
-Firstly set your `User` class as `Spree.user_class` in your `config/initializers/spree.rb` file:
-
-```ruby
-Spree.user_class = 'User'
-```
-
-Now, run the generator to set up Spree integration with Devise:
-
-
-```bash Spree CLI (Docker)
-spree generate spree:authentication:devise
-```
-
-```bash Without Spree CLI
-bin/rails g spree:authentication:devise
-```
-
-
-This will create a new file in `lib/spree/authentication_helpers.rb` that serves as a bridge between Spree and your existing authentication system routes. You can then use this file to customize the routes to your liking. It should automatically pick up standard Devise routes.
-
-Secondly, this generator will add necessary modules to your `User` model.
-
-```ruby
-# app/models/user.rb
-class User < ApplicationRecord
-  # ... your existing code ...
-
-  include Spree::UserAddress
-  include Spree::UserMethods
-  include Spree::UserPaymentSource
-end
-```
-
-This will ensure that your `User` model can be used as a Spree user.
-
-This generator will also add 2 new lines to your Spree initializer file:
-
-```ruby
-Devise.parent_controller = "Spree::BaseController"
-Devise.parent_mailer = "Spree::BaseMailer"
-```
-
-This ensures that Devise will use Spree storefront layout for login/signup/etc and use Spree mailer layout for sending emails so they'll match your Storefront branding.
-
-If you have more complex setup, you can remove these lines and customize the routes and mailer in your own initializer file.
-
-## Using Custom Authentication
-
-If you're using a custom authentication system, you can follow the steps below to integrate Spree with your existing authentication system.
-
-Firstly set your `User` class as `Spree.user_class` in your `config/initializers/spree.rb` file:
-
-```ruby
-Spree.user_class = 'User'
-```
-
-Now, run the generator to set up Spree integration with your custom authentication system:
-
-
-```bash Spree CLI (Docker)
-spree generate spree:authentication:custom
-```
-
-```bash Without Spree CLI
-bin/rails g spree:authentication:custom
-```
-
-
-This will create a new file in `lib/spree/authentication_helpers.rb` that serves as a bridge between Spree and your existing authentication system routes. You will need to customize this file to fit your needs.
-
-Secondly, this generator will add necessary modules to your `User` model.
-
-```ruby
-# app/models/user.rb
-class User < ApplicationRecord
-  # ... your existing code ...
-
-  include Spree::UserAddress
-  include Spree::UserMethods
-  include Spree::UserPaymentSource
-end
-```
-
-## Admin Panel authentication
-
-Please refer to the [Admin Panel Authentication](../admin/authentication.md) page for more details.

package/dist/developer/customization/checkout.md

@@ -1,202 +0,0 @@
----
-title: Checkout Flow
-description: Customize the Spree checkout flow with the checkout DSL — add, remove, or conditionally skip address, delivery, payment, and confirmation steps.
-version: v5
----
-
-## Overview
-
-The Spree checkout process has been designed for maximum flexibility. It's been redesigned several times now, each iteration has benefited from the feedback of real-world deployment experience. It is relatively simple to customize the checkout process to suit your needs. Secure transmission of customer information is possible via SSL and credit card information is never stored in the database.
-
-## The Checkout Flow DSL
-
-Spree comes with a new checkout DSL that allows you to succinctly define the different steps of your checkout. This new DSL allows you to customize _just_ the checkout flow, while maintaining the unrelated admin states, such as "canceled" and "resumed", that an order can transition to. Ultimately, it provides a shorter syntax compared with overriding the entire state machine for the `Spree::Order` class.
-
-The default checkout flow for Spree is defined like this, adequately demonstrating the abilities of this new system:
-
-```ruby
-checkout_flow do
-  go_to_state :address
-  go_to_state :delivery
-  go_to_state :payment, if: ->(order) {
-    order.update_totals
-    order.payment_required?
-  }
-  go_to_state :confirm, if: ->(order) { order.confirmation_required? }
-  go_to_state :complete
-  remove_transition from: :delivery, to: :confirm
-```
-
-we can pass a block on each checkout step definition and work some logic to figure if the step is required dynamically. e.g. the confirm step might only be necessary for payment gateways that support payment profiles.
-
-These conditional states present a situation where an order could transition from delivery to one of payment, confirm or complete. In the default checkout, we never want to transition from delivery to confirm, and therefore have removed it using the `remove_transition` method of the Checkout DSL. The resulting transitions between states look like the image below:
-
-These two helper methods are provided on `Spree::Order` instances for your convenience:
-
-* `checkout_steps` - returns a list of all the potential states of the checkout.
-* `has_step?` - Used to check if the current order fulfills the requirements for a specific state.
-
-If you want a list of all the currently available states for the checkout, use the `checkout_steps` method, which will return the steps in an array.
-
-## Default Checkout Steps
-
-The Spree checkout process consists of the following steps. With the exception of the Registration step, each of these steps corresponds to a state of the [Order object](../core-concepts/orders.md):
-
-* Shipping Address and Contact Information
-* Delivery Options Shipping Method
-* Payment and Billing Information
-* Confirmation (optional)
-
-The following sections will provide a walk-through of checkout from a user's perspective, and offer some information on how to configure the default behavior of the various steps.
-
-### Shipping Address and Contact Information
-
-This step allows the customer to add shipping information and contact information. Customers have also option to sign in or create an account. For payment methods such as Stripe customers can use quick checkout option via payment wallets such as Apple Pay, Google Pay, etc and skip the rest of the checkout process.
-
-The address fields include a select box for choosing state/province. If there are no states configured for a particular country, the select box will be replaced by a text field instead.
-
-The list of countries that appear in the country select box can also be configured. Spree will list all countries by default, but you can configure exactly which countries you would like to appear. The list can be limited to a specific set of countries by [setting the Store's checkout zone](../core-concepts/stores.md#checkout-configuration).
-
-### Delivery Options
-
-During this step, the user may choose a delivery method. Spree assumes the list of shipping methods to be dependent on the shipping address. If there are multiple shipments eg. different Stock Locations or Vendors, the user will be asked to select shipping method for each shipment.
-
-### Payment
-
-This step is where the customer provides payment and billing information. Spree does not store any payment information in the database. For payment methods such as Stripe, we use Stripe JavaScript SDKs to render their payment form inside the checkout page, fully compliant with PCI DSS standards.
-
-Besides Credit Card, Wallets and other 3rd party payment methods, Spree also supports Store Credit and Gift Cards (Spree 5.1+ only) which can be used to pay for the entire order or part of the order.
-
-For more information about payments, please see the [Payments guide](../core-concepts/payments.md).
-
-### Confirmation
-
-This is the final opportunity for the customer to review their order before submitting it to be processed. Users have the opportunity to return to any step in the process using either the back button or by clicking on the appropriate step in the "progress breadcrumb."
-
-This step is disabled by default, but can be enabled by two ways:
-
-1. globally for all orders by setting a preference in `config/initializers/spree.rb`:
-
-    ```ruby config/initializers/spree.rb
-    Spree::Config[:always_include_confirm_step] = true
-    ```
-
-2. conditionally for specific orders by overriding the `confirmation_required?` method in `Spree::Order` with a [decorator](decorators.md), eg.
-
-    ```ruby app/models/spree/order_decorator.rb
-    module Spree
-      module OrderDecorator
-        # require confirmation for orders with a US billing address
-        def confirmation_required?
-          billing_address&.country_iso == 'US'
-        end
-      end
-    end
-    ```
-
-## Adding Logic Before or After a Particular Step
-
-There are two approaches for adding logic around checkout state transitions:
-
-### Approach 1: Events Subscribers (Recommended for side effects)
-
-For actions that should happen **after** a checkout step completes (syncing with external services, sending notifications, logging, etc.), use [Events subscribers](../core-concepts/events.md). This is the recommended approach because it keeps your code decoupled from Spree internals.
-
-```ruby app/subscribers/order_completed_subscriber.rb
-class OrderCompletedSubscriber < Spree::Subscriber
-  subscribes_to 'order.completed'
-
-  def handle(event)
-    order = Spree::Order.find_by_prefix_id(event.payload['id'])
-    return unless order
-
-    # Sync to fulfillment system, notify warehouse, etc.
-    FulfillmentService.notify(order)
-    AnalyticsService.track_purchase(order)
-  end
-end
-```
-
-> **INFO:** Events are fired automatically when orders change state. See [Events documentation](../core-concepts/events.md#order-events) for all available order events.
-
-### Approach 2: State Machine Callbacks (For validation/blocking logic)
-
-The [state_machines](https://github.com/state-machines/state_machines) gem allows you to implement callbacks that can **block** transitions. Use this approach only when you need to prevent a transition based on validation logic.
-
-For example, if you wanted to verify that the user provides a valid zip code before transitioning to the delivery step:
-
-```ruby app/models/spree/order_decorator.rb
-module Spree
-  module OrderDecorator
-    def self.prepended(base)
-      base.state_machine.before_transition to: :delivery, do: :valid_zip_code?
-    end
-
-    def valid_zip_code?
-      # Return false to prevent the transition
-      ship_address&.zipcode&.match?(/^\d{5}(-\d{4})?$/)
-    end
-  end
-
-  Order.prepend(OrderDecorator)
-end
-```
-
-This callback would prevent transitioning to the `delivery` step if `valid_zip_code?` returns false.
-
-> **WARNING:** Avoid using state machine callbacks for side effects like API calls or notifications. These can slow down checkout and may fail silently. Use [Events subscribers](../core-concepts/events.md) instead.
-
-## Modifying the checkout flow
-
-To add or remove steps to the checkout flow, you can use the 
-[insert_checkout_step](https://github.com/spree/spree/blob/a39ed2b69f1f2b2f413b7f46090bd0deeb439d61/core/app/models/spree/order/checkout.rb#L138) and [remove_checkout_step](https://github.com/spree/spree/blob/a39ed2b69f1f2b2f413b7f46090bd0deeb439d61/core/app/models/spree/order/checkout.rb#L157) helpers respectively.
-
-The `insert_checkout_step` method takes a `before` or `after` option to determine where to insert the step:
-
-```ruby app/models/spree/order_decorator.rb
-module Spree
-  module OrderDecorator
-    def self.prepended(base)
-      base.insert_checkout_step :new_step, before: :address
-      # or
-      # base.insert_checkout_step :new_step, after: :address
-    end
-  end
-
-  Order.prepend(OrderDecorator)
-end
-```
-
-The `remove_checkout_step` will remove just one checkout step at a time:
-
-```ruby app/models/spree/order_decorator.rb
-module Spree
-  module OrderDecorator
-    def self.prepended(base)
-      base.remove_checkout_step :address
-      base.remove_checkout_step :delivery
-    end
-  end
-
-  Order.prepend(OrderDecorator)
-end
-```
-
-What will happen here is that when a user goes to checkout, they will be asked to potentially fill in their payment details and then potentially confirm the order. This is the default behavior of the payment and the confirm steps within the checkout. If they are not required to provide payment or confirmation for this order then checking out this order will result in its immediate completion.
-
-To completely re-define the flow of the checkout, use the `checkout_flow` helper:
-
-```ruby app/models/spree/order_decorator.rb
-module Spree
-  module OrderDecorator
-    def self.prepended(base)
-      base.checkout_flow do
-        go_to_state :payment
-        go_to_state :complete
-      end
-    end
-  end
-
-  Order.prepend(OrderDecorator)
-end
-```

package/dist/developer/customization/emails.md

@@ -1,18 +0,0 @@
----
-title: Emails
-description: Customize Spree transactional emails using the spree_emails gem and Postmark templates, including how to preview mailers locally during development.
----
-
-> **NOTE:** Emails are now part of `spree_emails` gem. If you use `spree_starter` you already have it installed.
-
-## Overview
-
-Spree uses [postmark templates](https://github.com/wildbit/postmark-templates), as a base for all transactional emails.
-
-## Email previews
-
-Spree bundles [ActionMailer previews](https://guides.rubyonrails.org/action_mailer_basics.html#previewing-and-testing-mailers) for all of its transactional emails. They are served automatically in development — there is nothing to install.
-
-Start the rails server locally and go to: `localhost:3000/rails/mailers`
-
-(it requires a seeded development database in order to work properly, as the previews render real records)

package/dist/developer/customization/routes.md

@@ -1,24 +0,0 @@
----
-title: Routes
-description: Learn how to customize the routes in Spree
----
-
-## Default configuration
-
-By default Spree is mounted at the root of your domain, this code will be inserted into `config/routes.rb`:
-
-```ruby
-mount Spree::Core::Engine, at: '/'
-```
-
-This means that Spree will be available at the root of your domain, for example `http://localhost:3000`.
-
-## Customizing the mount point
-
-You can customize this simply by changing the `:at` specification in `config/routes.rb` to be something else. For example, if you would like Spree to be mounted at `/shop`, you can write this:
-
-```ruby
-mount Spree::Core::Engine, at: `/shop`
-```
-
-The different parts of Spree (API, Admin) will be mounted there as well, eg. `http://localhost:3000/shop/products`.