@spree/docs 0.1.113 → 0.1.115

package/dist/api-reference/admin-api/endpoints.md

@@ -6,7 +6,7 @@ description: "Every Spree Admin API v3 endpoint at a glance — method, path, re
 
 {/* Generated from docs/api-reference/admin.yaml by packages/cli/scripts/generate-endpoints-doc.mjs — do not edit by hand. */}
 
-All 192 Admin API operations, with the [scope](authentication.md) a secret API key needs for each. JWT-authenticated admin users are governed by their roles instead of scopes. The same index is available offline via the CLI: `spree api endpoints`.
+All 209 Admin API operations, with the [scope](authentication.md) a secret API key needs for each. JWT-authenticated admin users are governed by their roles instead of scopes. The same index is available offline via the CLI: `spree api endpoints`.
 
 Endpoints marked — are exempt from scope checks (authentication and session endpoints) or resolve their scope at request time.
 
@@ -36,7 +36,9 @@ Endpoints marked — are exempt from scope checks (authentication and session en
 | `GET` | `/api_keys` | `read_api_keys` | List API keys |
 | `POST` | `/api_keys` | `write_api_keys` | Create an API key |
 | `GET` | `/api_keys/{id}` | `read_api_keys` | Show an API key |
+| `PATCH` | `/api_keys/{id}` | `write_api_keys` | Update an API key |
 | `DELETE` | `/api_keys/{id}` | `write_api_keys` | Delete an API key |
+| `GET` | `/api_keys/current` | *none* | Describe the current API key |
 | `PATCH` | `/api_keys/{id}/revoke` | `write_api_keys` | Revoke an API key |
 
 ## Auth
@@ -47,6 +49,20 @@ Endpoints marked — are exempt from scope checks (authentication and session en
 | `POST` | `/auth/refresh` | — | Refresh token |
 | `POST` | `/auth/logout` | — | Logout |
 
+## Categories
+
+| Method | Path | Required scope | Summary |
+|---|---|---|---|
+| `GET` | `/categories` | `read_categories` | List categories |
+| `POST` | `/categories` | `write_categories` | Create a category |
+| `GET` | `/categories/{id}` | `read_categories` | Get a category |
+| `PATCH` | `/categories/{id}` | `write_categories` | Update a category |
+| `DELETE` | `/categories/{id}` | `write_categories` | Delete a category |
+| `PATCH` | `/categories/{id}/reposition` | `write_categories` | Reposition a category |
+| `GET` | `/categories/{category_id}/products` | `read_categories` | List category products |
+| `POST` | `/categories/{category_id}/products` | `write_categories` | Add a product to a category |
+| `PATCH` | `/categories/{category_id}/products/{id}/reposition` | `write_categories` | Reposition a category product |
+
 ## Channels
 
 | Method | Path | Required scope | Summary |
@@ -141,6 +157,12 @@ Endpoints marked — are exempt from scope checks (authentication and session en
 | `DELETE` | `/invitations/{id}` | `write_settings` | Revoke an invitation |
 | `PATCH` | `/invitations/{id}/resend` | `write_settings` | Resend an invitation |
 
+## Locales
+
+| Method | Path | Required scope | Summary |
+|---|---|---|---|
+| `GET` | `/locales` | `read_settings` | List supported locales |
+
 ## Markets
 
 | Method | Path | Required scope | Summary |
@@ -156,6 +178,7 @@ Endpoints marked — are exempt from scope checks (authentication and session en
 | Method | Path | Required scope | Summary |
 |---|---|---|---|
 | `GET` | `/me` | — | Get current admin user and permissions |
+| `PATCH` | `/me` | — | Update the current admin profile |
 
 ## Option types
 
@@ -172,6 +195,7 @@ Endpoints marked — are exempt from scope checks (authentication and session en
 | Method | Path | Required scope | Summary |
 |---|---|---|---|
 | `GET` | `/orders/{order_id}/fulfillments` | `read_fulfillments` | List fulfillments |
+| `POST` | `/orders/{order_id}/fulfillments` | `write_fulfillments` | Create a fulfillment |
 | `GET` | `/orders/{order_id}/fulfillments/{id}` | `read_fulfillments` | Show a shipment |
 | `PATCH` | `/orders/{order_id}/fulfillments/{id}` | `write_fulfillments` | Update a shipment |
 | `PATCH` | `/orders/{order_id}/fulfillments/{id}/fulfill` | `write_fulfillments` | Fulfill a fulfillment |
@@ -246,6 +270,7 @@ Endpoints marked — are exempt from scope checks (authentication and session en
 | `GET` | `/products/{product_id}/custom_fields/{id}` | `read_products` | Show a product custom field |
 | `PATCH` | `/products/{product_id}/custom_fields/{id}` | `write_products` | Update a product custom field |
 | `DELETE` | `/products/{product_id}/custom_fields/{id}` | `write_products` | Delete a product custom field |
+| `GET` | `/products/{product_id}/translations` | `read_products` | List product translations |
 | `GET` | `/products` | `read_products` | List products |
 | `POST` | `/products` | `write_products` | Create a product |
 | `GET` | `/products/{id}` | `read_products` | Get a product |
@@ -331,6 +356,18 @@ Endpoints marked — are exempt from scope checks (authentication and session en
 |---|---|---|---|
 | `GET` | `/tags` | — | List tags |
 
+## Translatable resources
+
+| Method | Path | Required scope | Summary |
+|---|---|---|---|
+| `GET` | `/translatable_resources` | `read_settings` | List translatable resources |
+
+## Translations
+
+| Method | Path | Required scope | Summary |
+|---|---|---|---|
+| `POST` | `/translations/batch` | *write_<resource> for every resource type in the batch (for API-key authentication)* | Batch upsert translations |
+
 ## Webhook endpoints
 
 | Method | Path | Required scope | Summary |

package/dist/developer/multi-tenant/quickstart.md

@@ -18,7 +18,7 @@ Each tenant (store) can have its own isolated data and configuration, including:
 * store settings (name, logo, etc.)
 * etc.
 
-All data is fully isolated besided the staff users, which can manage multiple tenants. This allows you to create a SaaS platform where each tenant can have its own store with its own branding and configuration. Isolation works across admin dashboard and API.
+All data is fully isolated besides the staff users, which can manage multiple tenants. This allows you to create a SaaS platform where each tenant can have its own store with its own branding and configuration. Isolation works across admin dashboard and API.
 
 > **INFO:** If you need individual seller/supplier/vendor accounts but shared product listings under one site you should use [multi vendor recipe](../multi-vendor.md) instead.
 
@@ -32,9 +32,19 @@ All data is fully isolated besided the staff users, which can manage multiple te
 
 > **INFO:** You will need to add these environment variables to your CI/CD pipeline and staging/production environments.
 
-## Installing gems
+## Installation
 
-1. Add the following code to your `Gemfile`:
+### Eject the Spree backend
+
+If you've created your project with `create-spree-app` you will need to eject the backend to be able to install the Enterprise and Multi-Tenant gems. You can do this by running:
+
+```bash
+spree eject
+```
+
+### Adding gems
+
+1. Add the following code to your `backend/Gemfile`:
 
     ```ruby
     source "https://license:#{ENV['KEYGEN_LICENSE_KEY']}@rubygems.pkg.keygen.sh/#{ENV['KEYGEN_ACCOUNT_ID']}" do
@@ -43,7 +53,57 @@ All data is fully isolated besided the staff users, which can manage multiple te
     end
     ```
 
-2. Install gems:
+2. Configure the Docker image build to authenticate against the Keygen source.
+
+    If you use the Spree CLI (Docker), `spree bundle install` resolves the licensed
+    gems **inside the image at build time**, so the Keygen credentials must be available
+    during `bundle install` in the `Dockerfile` — not just at runtime. Pass them as
+    [BuildKit secrets](https://docs.docker.com/build/building/secrets/) so they are mounted
+    as environment variables for the `bundle install` step only, and never baked into the
+    image layers or history (unlike `ARG`/`ENV`/`COPY`).
+
+    > **INFO:** Skip this step if you install without the Spree CLI (plain `bundle install` on the host).
+>       In that case the Gemfile reads `KEYGEN_LICENSE_KEY` / `KEYGEN_ACCOUNT_ID` directly from
+>       your shell environment.
+
+    Wrap **every** `bundle install` in your `backend/Dockerfile` with the secret mounts. There
+    are usually two — one in the build stage and one in the dev stage:
+
+    ```dockerfile backend/Dockerfile
+    COPY .ruby-version Gemfile Gemfile.lock ./
+    RUN bundle install # [!code --]
+    RUN --mount=type=secret,id=keygen_license_key,env=KEYGEN_LICENSE_KEY,required=false \ # [!code ++]
+      --mount=type=secret,id=keygen_account_id,env=KEYGEN_ACCOUNT_ID,required=false \ # [!code ++]
+      bundle install # [!code ++]
+    ```
+
+    Then wire the secrets into **both** compose files (`docker-compose.yml` and
+    `docker-compose.dev.yml` — the latter is what `spree eject` copies over) so the CLI
+    supplies them to the build:
+
+    ```yaml docker-compose.yml
+    x-app: &app
+      build:
+        context: ./backend
+        dockerfile: Dockerfile
+        target: dev
+        secrets: # [!code ++]
+          - keygen_license_key # [!code ++]
+          - keygen_account_id # [!code ++]
+
+    # ...at the bottom of the file, declare where the secrets come from:
+    secrets: # [!code ++]
+      keygen_license_key: # [!code ++]
+        environment: KEYGEN_LICENSE_KEY # [!code ++]
+      keygen_account_id: # [!code ++]
+        environment: KEYGEN_ACCOUNT_ID # [!code ++]
+    ```
+
+    > **INFO:** Compose reads `environment:`-sourced secrets from the **shell environment** that runs
+>       the build, not from `.env`. Make sure `KEYGEN_LICENSE_KEY` and `KEYGEN_ACCOUNT_ID` are
+>       exported in the shell (and in your CI/CD and production build environments).
+
+3. Install gems:
 
     
 
@@ -57,7 +117,7 @@ All data is fully isolated besided the staff users, which can manage multiple te
 
     
 
-3. Run generators:
+4. Run generators:
 
     
 
@@ -72,9 +132,13 @@ All data is fully isolated besided the staff users, which can manage multiple te
     
 
     > **INFO:** This will copy and run migrations for `spree_enterprise` and `spree_multi_tenant` gems.
+>       The `spree_multi_tenant:install` generator also edits `config/routes.rb` (to add the
+>       tenant domain routing constraints), your customer user model, and your admin user model
+>       — see [Post-install configuration](#post-install-configuration) below.
 
+## Post-install configuration
 
-## Setting root domain
+### Setting root domain
 
 Usually multi-tenant applications are configured to use subdomains for each tenant. For example, if your root domain is `example.com`, you can have tenants like `tenant1.example.com`, `tenant2.example.com`, etc.
 To make it work you need to set the `Spree.root_domain` in your `config/initializers/spree.rb` file, eg.
@@ -86,23 +150,87 @@ Spree.root_domain = 'example.com'
 or use environment variable:
 
 ```ruby
-Spree.root_domain = ENV.fetch('SPREE_ROOT_DOMAIN', 'localhost')
+Spree.root_domain = ENV.fetch('SPREE_ROOT_DOMAIN', 'lvh.me')
+```
+
+You need to use `lvh.me` for local development, so cross-subdomain cookies will work, `localhost` will **not** work.
+
+> **WARNING:** `localhost` cannot be used as a cookie domain by browsers, so the session cookie set on
+>   `store1.localhost` is rejected and never sent back — you get logged out when moving between
+>   subdomains, and admin sign-in fails with `ActionController::InvalidAuthenticityToken`
+>   ("Can't verify CSRF token authenticity"). Use `lvh.me` (or `localtest.me`); both resolve to
+>   `127.0.0.1` and are valid cookie domains.
+
+#### Sharing the session cookie across subdomains
+
+For staff to stay signed in while moving between the app domain (`app.example.com`) and tenant
+subdomains (`store1.example.com`), the session cookie must be scoped to the parent domain. Set
+`COOKIE_TLD_LENGTH` to the number of labels in your root domain:
+
+| Root domain | `COOKIE_TLD_LENGTH` | Cookie domain |
+| ----------- | ------------------- | ------------- |
+| `lvh.me`    | `2`                 | `.lvh.me`     |
+| `example.com` | `2`               | `.example.com` |
+| `shop.example.co.uk` | `3`        | `.example.co.uk` |
+
+```bash .env
+SPREE_ROOT_DOMAIN=lvh.me
+COOKIE_TLD_LENGTH=2
 ```
 
-This way you can also test it locally using `localhost` as root domain, and use `tenant1.localhost`, `tenant2.localhost`, etc. for tenants.
+#### Allowing tenant subdomains through host authorization
+
+Rails' host authorization blocks unknown hosts. `.localhost` and `.test` are permitted in
+development by default, but `.lvh.me` (and your production domain) are not — requests to
+`app.lvh.me` are rejected with a "Blocked hosts" error until you allow them. Add your root
+domain to `config/environments/development.rb`:
+
+```ruby backend/config/environments/development.rb
+if (root_domain = ENV['SPREE_ROOT_DOMAIN']).present?
+  config.hosts << ".#{root_domain}"
+end
+```
 
-## Customer User Class adjustment
+### Customer User Class adjustment
 
 We need to make slight adjustments to the user class so it can work in a multi-tenant environment.
 
-You need to remove `:validatable` module. This module is responsible for validating the user's email uniqueness. We need to change it to validate it in the scope of the tenant.
+The `spree_multi_tenant:install` generator adds `include SpreeMultiTenant::CustomerUserConcern`
+to your customer user model automatically. You then need to **remove the `:validatable` module**
+manually. `:validatable` validates the user's email uniqueness globally; the concern re-validates
+it in the scope of the tenant instead, so the same email can exist across different tenants.
 
 ```ruby backend/app/models/spree/user.rb
-class User < ApplicationRecord
-  devise :database_authenticatable, :registerable, :validatable # [!code --]
-  devise :database_authenticatable, :registerable, # [!code ++]
-         :recoverable, :rememberable, :trackable, :confirmable
+class Spree::User < Spree.base_class
+  include Spree::UserAddress
+  include Spree::UserMethods
+  include Spree::UserPaymentSource
+  include SpreeMultiTenant::CustomerUserConcern # added by the generator
+
+  devise :database_authenticatable, :registerable, :recoverable, :rememberable, :validatable # [!code --]
+  devise :database_authenticatable, :registerable, :recoverable, :rememberable # [!code ++]
+end
+```
+
+> **WARNING:** Only remove `:validatable`. Do not add other Devise modules (such as `:confirmable`) here
+>   unless your app is already set up for them — `:confirmable`, for example, requires additional
+>   columns and a confirmation flow, and adding it will break sign-in.
 
-  include SpreeMultiTenant::CustomerUserConcern # [!code ++]
+### Admin User Class adjustment
+
+The generator also changes your admin user model's base class from `Spree.base_class` to
+`Spree::Base`. If your `admin_user.rb` exists, this is applied automatically; otherwise make the
+change yourself:
+
+```ruby backend/app/models/spree/admin_user.rb
+class Spree::AdminUser < Spree.base_class # [!code --]
+class Spree::AdminUser < Spree::Base # [!code ++]
+  include Spree::AdminUserMethods
+
+  devise :database_authenticatable, :registerable,
+         :recoverable, :rememberable, :validatable
 end
 ```
+
+> **INFO:** Unlike the customer user model, the admin user model keeps `:validatable` — staff accounts are
+>   global and can manage multiple tenants, so their emails remain globally unique.

package/package.json

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