@spree/docs 0.1.0

package/dist/developer/how-to/custom-report.md

@@ -0,0 +1,387 @@
+---
+title: Build a Custom Report
+description: Step-by-step guide to creating custom reports with data queries, line item formatters, and CSV export.
+---
+
+## Overview
+
+Spree's reporting system is designed for extension. Each report is a pair of classes — a **Report** that defines the data query and a **ReportLineItem** that formats each row — registered in `Spree.reports` so it appears in the admin UI.
+
+This guide walks you through building a custom report from scratch, including advanced patterns for SQL aggregations and multi-vendor support.
+
+Before starting, make sure you understand [how the reporting system works](/developer/core-concepts/reports).
+
+## Creating a Custom Report
+
+### Step 1: Create the Report Class
+
+Create a new report class inheriting from `Spree::Report`. The key method to implement is `line_items_scope`, which returns an `ActiveRecord::Relation` defining the records in your report:
+
+```ruby app/models/spree/reports/customer_orders.rb
+module Spree
+  module Reports
+    class CustomerOrders < Spree::Report
+      # Define the scope of records to include in the report
+      def line_items_scope
+        store.orders.complete.where(
+          completed_at: date_from..date_to,
+          currency: currency
+        ).includes(:user, :bill_address)
+      end
+    end
+  end
+end
+```
+
+The `line_items_scope` method has access to:
+
+| Helper | Description |
+|--------|-------------|
+| `store` | The current store |
+| `date_from` | Report start date |
+| `date_to` | Report end date |
+| `currency` | Report currency |
+| `vendor` | Vendor (if multi-vendor is enabled) |
+
+### Step 2: Create the Line Item Class
+
+Create a corresponding line item class that transforms each record into report columns. The class name must match the report class name (e.g., `Reports::CustomerOrders` → `ReportLineItems::CustomerOrders`):
+
+```ruby app/models/spree/report_line_items/customer_orders.rb
+module Spree
+  module ReportLineItems
+    class CustomerOrders < Spree::ReportLineItem
+      # Define attributes that will become columns
+      attribute :order_number, :string
+      attribute :completed_at, :string
+      attribute :customer_email, :string
+      attribute :customer_name, :string
+      attribute :item_count, :integer
+      attribute :total, :string
+
+      # Map record fields to report columns
+      def order_number
+        record.number
+      end
+
+      def completed_at
+        record.completed_at.strftime('%Y-%m-%d %H:%M')
+      end
+
+      def customer_email
+        record.email
+      end
+
+      def customer_name
+        record.bill_address&.full_name
+      end
+
+      def item_count
+        record.line_items.sum(:quantity)
+      end
+
+      def total
+        Spree::Money.new(record.total, currency: currency)
+      end
+    end
+  end
+end
+```
+
+**Important notes:**
+- Use `attribute` to define columns with their types — these become CSV headers
+- Each attribute needs a corresponding method that extracts/formats data from `record`
+- `record` is a single item from `line_items_scope`
+- Use `Spree::Money` for currency formatting
+- `currency` and `store` are delegated from the report
+
+#### Available Base Class Methods
+
+`Spree::ReportLineItem` provides:
+
+```ruby
+# Returns column headers for display
+self.headers
+# => [{ name: :order_number, label: "Order Number" }, ...]
+
+# Returns column names for CSV header row
+self.csv_headers
+# => ["order_number", "completed_at", "customer_email", ...]
+
+# Converts line item to CSV row array
+to_csv
+# => ["R123456", "2025-01-15 14:30", "john@example.com", ...]
+```
+
+### Step 3: Register the Report
+
+Add your report to the registry in an initializer:
+
+```ruby config/initializers/spree.rb
+Rails.application.config.after_initialize do
+  Spree.reports << Spree::Reports::CustomerOrders
+end
+```
+
+### Step 4: Add Translations
+
+Add the report name and column header translations:
+
+```yaml config/locales/en.yml
+en:
+  spree:
+    report_names:
+      customer_orders: Customer Orders
+    order_number: Order Number
+    completed_at: Completed At
+    customer_email: Customer Email
+    customer_name: Customer Name
+    item_count: Item Count
+    total: Total
+```
+
+After restarting your application, the new report will be available in **Admin > Reports**.
+
+## Advanced Patterns
+
+### Complex Queries with Aggregations
+
+For reports that aggregate data across records, use SQL directly in `line_items_scope`:
+
+```ruby app/models/spree/reports/revenue_by_category.rb
+module Spree
+  module Reports
+    class RevenueByCategory < Spree::Report
+      def line_items_scope
+        line_items_sql = Spree::LineItem
+          .joins(:order)
+          .where(
+            spree_orders: {
+              completed_at: date_from..date_to,
+              currency: currency
+            }
+          )
+          .select(
+            "spree_line_items.variant_id",
+            "SUM(spree_line_items.quantity) as quantity",
+            "SUM(spree_line_items.pre_tax_amount) as revenue"
+          )
+          .group(:variant_id)
+          .to_sql
+
+        store.taxons
+          .where(depth: 1)  # Top-level categories
+          .joins("LEFT JOIN spree_products_taxons ON spree_products_taxons.taxon_id = spree_taxons.id")
+          .joins("LEFT JOIN spree_variants ON spree_variants.product_id = spree_products_taxons.product_id")
+          .joins("LEFT JOIN (#{line_items_sql}) AS line_items ON line_items.variant_id = spree_variants.id")
+          .select(
+            "spree_taxons.*",
+            "COALESCE(SUM(line_items.quantity), 0) AS total_quantity",
+            "COALESCE(SUM(line_items.revenue), 0.0) AS total_revenue"
+          )
+          .group("spree_taxons.id")
+      end
+    end
+  end
+end
+```
+
+When using aggregated queries, the `record` in your line item class will have virtual attributes (like `total_quantity`, `total_revenue`) available as methods.
+
+### Custom Summary Section
+
+Override `summary` to provide aggregate metrics alongside the line items:
+
+```ruby app/models/spree/reports/customer_orders.rb
+module Spree
+  module Reports
+    class CustomerOrders < Spree::Report
+      def summary
+        {
+          total_orders: line_items_scope.count,
+          total_revenue: line_items_scope.sum(:total),
+          average_order_value: line_items_scope.average(:total)
+        }
+      end
+    end
+  end
+end
+```
+
+### Multi-Vendor Support
+
+If you're using Spree Multi-Vendor, filter by vendor when one is selected:
+
+```ruby app/models/spree/reports/vendor_sales.rb
+module Spree
+  module Reports
+    class VendorSales < Spree::Report
+      def line_items_scope
+        scope = store.line_items.where(
+          order: Spree::Order.complete.where(
+            completed_at: date_from..date_to,
+            currency: currency
+          )
+        )
+
+        # Filter by vendor if one is selected
+        scope = scope.where(vendor_id: vendor.id) if defined?(vendor) && vendor.present?
+
+        scope
+      end
+    end
+  end
+end
+```
+
+## Testing Custom Reports
+
+### Testing the Report Class
+
+Test that your report's `line_items_scope` returns the correct records:
+
+```ruby spec/models/spree/reports/customer_orders_spec.rb
+require 'rails_helper'
+
+RSpec.describe Spree::Reports::CustomerOrders, type: :model do
+  let(:store) { create(:store) }
+  let(:user) { create(:admin_user) }
+
+  subject(:report) do
+    described_class.new(
+      store: store,
+      user: user,
+      currency: 'USD',
+      date_from: 1.month.ago,
+      date_to: Time.current
+    )
+  end
+
+  describe '#line_items_scope' do
+    let!(:completed_order) do
+      create(:completed_order_with_totals, store: store, currency: 'USD', completed_at: 1.week.ago)
+    end
+
+    let!(:incomplete_order) do
+      create(:order, store: store, currency: 'USD', state: 'cart')
+    end
+
+    let!(:other_currency_order) do
+      create(:completed_order_with_totals, store: store, currency: 'EUR', completed_at: 1.week.ago)
+    end
+
+    let!(:old_order) do
+      create(:completed_order_with_totals, store: store, currency: 'USD', completed_at: 2.months.ago)
+    end
+
+    it 'returns only completed orders within the date range and currency' do
+      scope = report.line_items_scope
+
+      expect(scope).to include(completed_order)
+      expect(scope).not_to include(incomplete_order)
+      expect(scope).not_to include(other_currency_order)
+      expect(scope).not_to include(old_order)
+    end
+  end
+
+  describe '#line_items' do
+    let!(:order) do
+      create(:completed_order_with_totals, store: store, currency: 'USD', completed_at: 1.week.ago)
+    end
+
+    it 'returns ReportLineItem objects' do
+      items = report.line_items
+      expect(items).to all(be_a(Spree::ReportLineItems::CustomerOrders))
+    end
+
+    it 'respects the limit option' do
+      create(:completed_order_with_totals, store: store, currency: 'USD', completed_at: 2.days.ago)
+      items = report.line_items(limit: 1)
+      expect(items.length).to eq(1)
+    end
+  end
+end
+```
+
+### Testing the ReportLineItem Class
+
+Test that your line item correctly formats each record:
+
+```ruby spec/models/spree/report_line_items/customer_orders_spec.rb
+require 'rails_helper'
+
+RSpec.describe Spree::ReportLineItems::CustomerOrders, type: :model do
+  let(:store) { create(:store) }
+  let(:user) { create(:admin_user) }
+  let(:bill_address) { create(:address) }
+  let(:order) do
+    create(:completed_order_with_totals,
+           store: store,
+           currency: 'USD',
+           completed_at: 1.week.ago,
+           bill_address: bill_address)
+  end
+
+  let(:report) do
+    Spree::Reports::CustomerOrders.new(
+      store: store,
+      user: user,
+      currency: 'USD',
+      date_from: 1.month.ago,
+      date_to: Time.current
+    )
+  end
+
+  subject(:line_item) { described_class.new(record: order, report: report) }
+
+  describe '#order_number' do
+    it 'returns the order number' do
+      expect(line_item.order_number).to eq(order.number)
+    end
+  end
+
+  describe '#customer_name' do
+    it 'returns the billing address full name' do
+      expect(line_item.customer_name).to eq(bill_address.full_name)
+    end
+
+    context 'when no billing address' do
+      let(:bill_address) { nil }
+
+      it 'returns nil' do
+        order.update_column(:bill_address_id, nil)
+        order.reload
+        expect(line_item.customer_name).to be_nil
+      end
+    end
+  end
+
+  describe '#total' do
+    it 'returns a Spree::Money formatted total' do
+      result = line_item.total
+      expect(result).to be_a(Spree::Money)
+      expect(result.money.to_f).to eq(order.total.to_f)
+    end
+  end
+
+  describe '#to_csv' do
+    it 'returns an array of values for CSV row' do
+      csv_row = line_item.to_csv
+      expect(csv_row.length).to eq(6)
+      expect(csv_row[0]).to eq(order.number)
+    end
+  end
+end
+```
+
+### Key Testing Patterns
+
+1. **Test scope filtering** — verify `line_items_scope` returns only records matching date range, currency, and store
+2. **Test attribute formatting** — verify each attribute method returns correctly formatted data
+3. **Test CSV output** — check `headers`, `csv_headers`, and `to_csv` return expected values
+4. **Test edge cases** — handle nil values gracefully (e.g., missing addresses)
+
+## Related Documentation
+
+- [Reports](/developer/core-concepts/reports) - Report architecture and built-in reports
+- [Events](/developer/core-concepts/events) - How report generation uses the events system

package/dist/developer/how-to/custom-search-provider.md

@@ -0,0 +1,230 @@
+---
+title: Build a Custom Search Provider
+description: Step-by-step guide to building a custom search provider for Spree, integrating external search engines like Typesense, Algolia, or Elasticsearch.
+---
+
+## Overview
+
+This guide walks you through building a custom search provider for Spree. By the end, you'll have a fully functional search integration that:
+
+- Powers product search, filtering, sorting, and faceted navigation
+- Handles multi-locale and multi-currency indexing automatically
+- Integrates with the Store API without any frontend changes
+- Supports background indexing and bulk reindex
+
+Before starting, make sure you understand [how search and filtering works in Spree](/developer/core-concepts/search-filtering).
+
+> **INFO:** Spree ships with a built-in [Meilisearch provider](/integrations/search/meilisearch). If Meilisearch fits your needs, you don't need to build a custom provider — just configure it.
+
+## Architecture
+
+```
+Store API Request (locale=de, currency=EUR)
+  │
+  ├─ AR Scope (security + visibility)
+  │   store.products.active(currency).accessible_by(ability)
+  │
+  └─ Search Provider (search + filter + facets)
+       ├─ Database (default): ILIKE + Ransack + FiltersAggregator
+       ├─ Meilisearch (built-in): one API call with locale/currency filtering
+       └─ Your Provider: implements the same interface
+```
+
+The controller builds a base ActiveRecord scope for **security and visibility**, then delegates **everything else** to your search provider.
+
+## Step 1: Create the Provider Class
+
+Create a class that inherits from `Spree::SearchProvider::Base` and implements `search_and_filter`:
+
+```ruby app/models/my_app/search_provider/typesense.rb
+module MyApp
+  module SearchProvider
+    class Typesense < Spree::SearchProvider::Base
+      # Enable background indexing jobs
+      def self.indexing_required?
+        true
+      end
+
+      def initialize(store)
+        super
+        require 'typesense'
+      rescue LoadError
+        raise LoadError, "Add `gem 'typesense'` to your Gemfile"
+      end
+    end
+  end
+end
+```
+
+`indexing_required?` returning `true` tells the `SearchIndexable` concern to enqueue background jobs when products are created, updated, or destroyed.
+
+## Step 2: Implement `search_and_filter`
+
+This is the core method. It receives a base AR scope (already filtered for security) and must return a `SearchResult`:
+
+```ruby app/models/my_app/search_provider/typesense.rb
+def search_and_filter(scope:, query: nil, filters: {}, sort: nil, page: 1, limit: 25)
+  page = [page.to_i, 1].max
+  limit = limit.to_i.clamp(1, 100)
+
+  # 1. Query your search engine with locale/currency filtering
+  results = client.collections[index_name].documents.search({
+    q: query || '*',
+    query_by: 'name,description,sku,option_values,category_names,tags',
+    filter_by: build_filters(filters),
+    sort_by: build_sort(sort),
+    page: page,
+    per_page: limit,
+    facet_by: 'in_stock,price,category_ids,option_value_ids'
+  })
+
+  # 2. Extract product IDs (documents have composite IDs, extract product_id)
+  product_ids = results['hits'].map { |h| h['document']['product_id'] }.uniq
+  raw_ids = product_ids.filter_map { |pid| Spree::Product.decode_prefixed_id(pid) }
+
+  # 3. Intersect with AR scope (safety net for authorization)
+  products = raw_ids.any? ? scope.where(id: raw_ids).reorder(nil) : scope.none
+
+  # 4. Build Pagy for pagination metadata
+  require 'pagy'
+  pagy = Pagy::Offset.new(count: results['found'], page: page, limit: limit)
+
+  # 5. Return a SearchResult
+  Spree::SearchProvider::SearchResult.new(
+    products: products,
+    filters: build_facet_response(results['facet_counts']),
+    sort_options: %w[price -price name -name best_selling -available_on].map { |id| { id: id } },
+    default_sort: 'manual',
+    total_count: results['found'],
+    pagy: pagy
+  )
+end
+```
+
+> **WARNING:** Always filter by `locale`, `currency`, `store_ids`, `status='active'`, and `discontinue_on` in your search engine — not just in the AR scope. This ensures pagination counts are accurate. The AR scope is a safety net, not the primary filter.
+
+## Step 3: Implement Indexing
+
+Products are indexed as **one document per market × locale** combination. The `ProductPresenter` handles this automatically:
+
+```ruby app/models/my_app/search_provider/typesense.rb
+def index(product)
+  documents = Spree::SearchProvider::ProductPresenter.new(product, store).call
+  documents.each do |doc|
+    client.collections[index_name].documents.upsert(doc)
+  end
+end
+
+def remove(product)
+  remove_by_id(product.prefixed_id)
+end
+
+def remove_by_id(prefixed_id)
+  # Delete all locale/currency variants of this product
+  client.collections[index_name].documents.delete(
+    filter_by: "product_id:=#{prefixed_id}"
+  )
+end
+```
+
+The `ProductPresenter` returns an array of documents. For a store with US (USD/English) and EU (EUR/German+French) markets, one product produces 3 documents — each with flat `name`, `price`, `locale`, `currency` fields.
+
+## Step 4: Implement Bulk Reindex
+
+Use `ProductPresenter::REQUIRED_PRELOADS` to avoid N+1 queries:
+
+```ruby app/models/my_app/search_provider/typesense.rb
+def reindex(scope = nil)
+  scope ||= store.products
+  ensure_index_settings!
+
+  scope.reorder(id: :asc)
+       .preload(*Spree::SearchProvider::ProductPresenter::REQUIRED_PRELOADS)
+       .find_in_batches(batch_size: 500) do |batch|
+    documents = batch.flat_map { |p| Spree::SearchProvider::ProductPresenter.new(p, store).call }
+    index_batch(documents)
+  end
+end
+
+def index_batch(documents)
+  client.collections[index_name].documents.import(documents, action: 'upsert')
+end
+
+def ensure_index_settings!
+  # Create/update your collection schema here
+end
+```
+
+> **INFO:** Use `flat_map` (not `map`) because `ProductPresenter#call` returns an array of documents per product.
+
+## Step 5: Register the Provider
+
+```ruby config/initializers/spree.rb
+Spree.search_provider = 'MyApp::SearchProvider::Typesense'
+```
+
+Then reindex:
+
+```bash
+rake spree:search:reindex
+```
+
+## Provider Contract Reference
+
+| Method | Required | Description |
+|--------|----------|-------------|
+| `search_and_filter(scope:, query:, filters:, sort:, page:, limit:)` | Yes | Search, filter, sort, paginate, and return facets. Must return a `SearchResult`. |
+| `self.indexing_required?` | Yes | Return `true` to enable background indexing jobs. |
+| `index(product)` | Yes | Index a single product. `ProductPresenter#call` returns an array of documents. |
+| `remove(product)` | Yes | Remove all locale/currency variants from the index. |
+| `remove_by_id(prefixed_id)` | Yes | Remove by prefixed product ID (product may already be deleted). |
+| `reindex(scope)` | Yes | Bulk reindex with `ensure_index_settings!` + batch indexing. |
+| `index_batch(documents)` | Yes | Index a batch of pre-serialized documents. |
+| `ensure_index_settings!` | No | Configure index schema. Called by `reindex` and rake task. |
+
+### SearchResult
+
+```ruby
+Spree::SearchProvider::SearchResult.new(
+  products: ar_relation,                          # ActiveRecord::Relation
+  filters: [...],                                 # Array of facet hashes
+  sort_options: [{ id: 'price' }, ...],           # Array of sort option objects
+  default_sort: 'manual',                         # Default sort string
+  total_count: 150,                               # Total before pagination
+  pagy: pagy_object                               # Pagy::Offset or Pagy::Meilisearch
+)
+```
+
+### ProductPresenter
+
+```ruby
+documents = Spree::SearchProvider::ProductPresenter.new(product, store).call
+# => [
+#   { prefixed_id: "prod_abc_en_USD", product_id: "prod_abc", locale: "en",
+#     currency: "USD", name: "Blue Shirt", price: 29.99, ... },
+#   { prefixed_id: "prod_abc_de_EUR", product_id: "prod_abc", locale: "de",
+#     currency: "EUR", name: "Blaues Hemd", price: 27.50, ... }
+# ]
+```
+
+### Indexing Lifecycle
+
+The `Spree::SearchIndexable` concern on Product provides:
+
+| Method | Description |
+|--------|-------------|
+| `product.add_to_search_index` | Index synchronously (inline) |
+| `product.remove_from_search_index` | Remove synchronously (inline) |
+| `product.search_presentation` | Preview the documents that would be indexed |
+| `rake spree:search:reindex` | Bulk reindex all products |
+
+Background jobs (`IndexJob`, `RemoveJob`) fire on `after_commit` when `indexing_required?` is `true`.
+
+### Important: Prefixed IDs
+
+Always use prefixed IDs (`ctg_abc`, `prod_xyz`, `optval_abc`) when indexing. Never use raw database IDs — Spree supports UUID primary keys.
+
+## Related Documentation
+
+- [Search & Filtering](/developer/core-concepts/search-filtering) — Store API search reference
+- [Meilisearch Integration](/integrations/search/meilisearch) — Built-in Meilisearch provider setup

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

@@ -0,0 +1,71 @@
+---
+title: Multi-Store Spree Commerce
+sidebarTitle: Quickstart
+---
+
+To enable multiple stores, you will need to add the `spree_multi_store` gem to your project via:
+
+```bash
+bundle add spree_multi_store
+```
+
+> **INFO:** Spree Multi-Store is licensed under the [AGPL v3 License](https://opensource.org/licenses/AGPL-3.0). 
+> 
+> If you would like to use it in a commercial application, please [contact us](https://spreecommerce.org/get-started/) to obtain a commercial license.
+
+![](/images/mulit_store_978x2.png)
+
+## Store resources
+
+Each Store can have its own resources. For example, a Store can have its own Products, Taxonomies, Promotions, etc.
+
+| Resource                                          | Relationship                                                                                                                               |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| [**Order**](/core-concepts/orders)                            | One Order belongs to one Store                                                                                                             |
+| [**Product**](/core-concepts/products)                        | One Product can be associated with many Store(s), you can pick and choose in which Store(s) each Product will be available                 |
+| [**Payment Method**](/core-concepts/payments)                 | One Payment Method can be associated with many Store(s), you can select in which Stores given Payment Method will be available on Checkout |
+| [**Taxonomy**](/core-concepts/products#taxons-and-taxonomies) | One Taxonomy belongs to one Store                                                                                                          |
+| [**Promotion**](/core-concepts/promotions)                    | One Promotion can be associated with multiple Stores                                                                                       |
+| **Store Credit**                                  | One Store Credit belongs to and can be used in one Store
+
+## Current Store
+
+Spree will try to determine the current store based on the current URL. If the URL does not match any of the stores in the database, Spree will fall back to the default store.
+
+All Spree controllers or any other controllers that include [Spree::Core::ControllerHelpers::Store](https://github.com/spree/spree/blob/main/core/lib/spree/core/controller_helpers/store.rb) have access to the `current_store` method which returns the `Store` matching the current URL.
+
+All parts of Spree (API, Admin Panel) have this implemented.
+
+> **INFO:** Under the hood `current_store` calls [Spree::Stores::FindCurrent.new(url: url).execute](https://github.com/spree/spree/blob/main/core/app/finders/spree/stores/find_current.rb).
+> 
+> This logic can be easily overwritten by setting 
+> 
+> ```ruby
+Spree::Dependencies.current_store_finder = 'MyStoreFinderClass'
+```
+> 
+> in `config/initializers/spree.rb` file
+
+## Default Store
+
+If the system cannot find any Store that matches the current URL it will fall back to the Default Store.
+
+You can set the default Store via Rails console:
+
+```ruby
+Spree::Store.find(2).update(default: true)
+```
+
+To get the default store in your code or rails console type:
+
+```ruby
+Spree::Store.default
+```
+
+## Custom Domains
+
+Spree supports managing custom domains for Stores. In the Admin Panel, you can manage custom domains for each Store in the **Settings -> Domains** page.
+
+## Setup multi-store application
+
+[Follow the setup guide](/developer/multi-store/setup) to get started.