@spree/docs 0.1.177 → 0.1.178

package/dist/developer/tutorial/extending-models.md

@@ -1,393 +0,0 @@
----
-title: Extending Core Models
-description: Tutorial — extend Spree's core models with a custom Brand resource, generate a migration, and associate it with Products via a decorator.
----
-
-> **NOTE:** This is a backend customization. You need to perform it in the `backend` directory if you used `create-spree-app` to set up your Spree application.
-
-In this tutorial, we'll connect our custom Brand model with Spree's core Product model. This is a common pattern when building features that need to integrate with existing Spree functionality.
-
-> **INFO:** This guide assumes you've completed the [Model](model.md) and [Admin](admin.md) tutorials.
-
-## What We're Building
-
-By the end of this tutorial, you'll have:
-
-- Products associated with Brands
-- A brand selector in the Product admin form
-- Understanding of how to safely extend Spree core models
-
-## Choosing the Right Approach
-
-Before extending Spree models, consider which approach fits your needs best:
-
-| What you need | Recommended approach |
-|---------------|---------------------|
-| Add association (belongs_to, has_many) | **Decorator** (this tutorial) |
-| Add validation or scope | **Decorator** |
-| Add new instance/class method | **Decorator** |
-| React to model changes (after save, etc.) | [Events subscriber](../core-concepts/events.md) |
-| Sync with external service on changes | [Events](../core-concepts/events.md) or [Webhooks](../core-concepts/webhooks.md) |
-| Add searchable/filterable field | [Ransack configuration](../core-concepts/search-filtering.md#extending-ransackable-configuration) |
-| Add admin UI elements | [Admin Partials](../admin/extending-ui.md) |
-
-> **INFO:** This tutorial uses **decorators** because we're adding a structural association between models. For behavioral changes like callbacks, prefer [Events](../core-concepts/events.md) instead - they're easier to test and maintain.
-
-## Understanding Decorators
-
-When working with Spree, you'll often need to add functionality to existing models like `Spree::Product` or `Spree::Order`. However, you shouldn't modify these files directly because:
-
-1. **Upgrades** - Your changes would be lost when updating Spree
-2. **Maintainability** - It's hard to track what you've customized
-3. **Conflicts** - Direct modifications can conflict with Spree's code
-
-Instead, we use **decorators** - a Ruby pattern that lets you add or modify behavior of existing classes without changing their original source code.
-
-### How Decorators Work
-
-In Ruby, classes are "open" - you can add methods to them at any time. Decorators leverage this by:
-
-1. Creating a module with your new methods
-2. Using `Module#prepend` to inject your module into the class's inheritance chain
-3. Your methods run first, and can call `super` to invoke the original method
-
-```ruby
-# This is the basic pattern
-module Spree
-  module ProductDecorator
-    # Add a new method
-    def my_new_method
-      "Hello from decorator!"
-    end
-
-    # Override an existing method
-    def existing_method
-      # Do something before
-      result = super  # Call the original method
-      # Do something after
-      result
-    end
-  end
-
-  Product.prepend(ProductDecorator)
-end
-```
-
-The key line is `Product.prepend(ProductDecorator)` - this inserts your module at the beginning of the method lookup chain, so your methods are found first.
-
-## Step 1: Create the Migration
-
-First, add a `brand_id` column to the products table:
-
-
-```bash Spree CLI (Docker)
-spree generate migration AddBrandIdToSpreeProducts brand_id:integer:index
-```
-
-```bash Without Spree CLI
-bin/rails g migration AddBrandIdToSpreeProducts brand_id:integer:index
-```
-
-
-Edit the migration to add an index (but no foreign key constraint, keeping it optional):
-
-```ruby db/migrate/XXXXXXXXXXXXXX_add_brand_id_to_spree_products.rb
-class AddBrandIdToSpreeProducts < ActiveRecord::Migration[8.0]
-  def change
-    add_column :spree_products, :brand_id, :integer
-    add_index :spree_products, :brand_id
-  end
-end
-```
-
-Run the migration:
-
-
-```bash Spree CLI (Docker)
-spree migrate
-```
-
-```bash Without Spree CLI
-bin/rails db:migrate
-```
-
-
-> **INFO:** We intentionally don't add a foreign key constraint. This keeps the association optional and avoids issues if brands are deleted. Spree follows this pattern for flexibility.
-
-## Step 2: Generate the Product Decorator
-
-Spree provides a generator to create decorator files with the correct structure:
-
-
-```bash Spree CLI (Docker)
-spree generate model_decorator Spree::Product
-```
-
-```bash Without Spree CLI
-bin/rails g spree:model_decorator Spree::Product
-```
-
-
-This creates `app/models/spree/product_decorator.rb`:
-
-```ruby app/models/spree/product_decorator.rb
-module Spree
-  module ProductDecorator
-    def self.prepended(base)
-      # Class-level configurations go here
-    end
-  end
-
-  Product.prepend(ProductDecorator)
-end
-```
-
-## Step 3: Add the Brand Association to Product
-
-Update the decorator to add the `belongs_to` association:
-
-```ruby app/models/spree/product_decorator.rb {4}
-module Spree
-  module ProductDecorator
-    def self.prepended(base)
-      base.belongs_to :brand, class_name: 'Spree::Brand', optional: true
-    end
-  end
-
-  Product.prepend(ProductDecorator)
-end
-```
-
-### Understanding the Code
-
-- `self.prepended(base)` - This callback runs when the module is prepended to a class. The `base` parameter is the class being decorated (`Spree::Product`)
-- `base.belongs_to` - We call class methods on `base` to add associations, validations, scopes, etc.
-- `optional: true` - Products don't require a brand (the `brand_id` can be `NULL`)
-
-## Step 4: Add Products Association to Brand
-
-Now update your Brand model to define the reverse association:
-
-```ruby app/models/spree/brand.rb {5}
-module Spree
-  class Brand < Spree::Base
-    # ... existing code ...
-
-    has_many :products, class_name: 'Spree::Product', dependent: :nullify
-
-    # ... rest of your model ...
-  end
-end
-```
-
-> **INFO:** We use `dependent: :nullify` instead of `dependent: :destroy`. When a brand is deleted, products will have their `brand_id` set to `NULL` rather than being deleted. This is safer for e-commerce data.
-
-## Step 5: Permit the Brand Parameter
-
-For the admin form to save the brand association, we need to permit the `brand_id` parameter.
-
-Add to your Spree initializer:
-
-```ruby config/initializers/spree.rb {3}
-# .. other code ..
-
-Spree::PermittedAttributes.product_attributes << :brand_id
-```
-
-## Step 6: Add Brand Selector to Product Admin Form
-
-Create a partial to inject the brand selector into the product form. Spree's admin product form has injection points for customization.
-
-Create the partial:
-
-```erb app/views/spree/admin/products/_brand_field.html.erb
-<div class="card mb-6">
-  <div class="card-header">
-    <h5 class="card-title"><%= Spree.t(:brand) %></h5>
-  </div>
-  <div class="card-body">
-  <%= f.spree_select :brand_id,
-      Spree::Brand.order(:name).pluck(:name, :id),
-      { include_blank: true, label: Spree.t(:brand) } %>
-</div>
-```
-
-Register this partial to appear in the product form. Add to your initializer:
-
-**Spree 5.2+:**
-
-```ruby config/initializers/spree.rb
-    Rails.application.config.after_initialize do
-      Spree.admin.partials.product_form_sidebar << 'spree/admin/products/brand_field'
-    end
-    ```
-
-  **Spree 5.1 and below:**
-
-```ruby config/initializers/spree.rb
-    Rails.application.config.spree_admin.product_form_sidebar_partials << 'spree/admin/products/brand_field'
-    ```
-
-
-## Step 7: Add Translation
-
-Add the translation for the brand label:
-
-```yaml config/locales/en.yml
-en:
-  spree:
-    brand: Brand
-```
-
-## Testing the Association
-
-Verify everything works in the Rails console:
-
-```ruby
-# Create a brand and product
-brand = Spree::Brand.create!(name: 'Nike')
-product = Spree::Product.first
-product.update!(brand: brand)
-
-# Test associations
-product.brand        # => #<Spree::Brand id: 1, name: "Nike"...>
-brand.products       # => [#<Spree::Product...>]
-brand.products.count # => 1
-```
-
-## Decorator Best Practices
-
-
-  - **Use prepended callback** — Always use `self.prepended(base)` for class-level additions like associations, validations, and scopes.
-
-  - **Keep decorators focused** — Each decorator should have a single responsibility. Create multiple decorators if needed.
-
-  - **Call super when overriding** — When overriding methods, call `super` to preserve original behavior unless you intentionally want to replace it.
-
-  - **Test decorated behavior** — Write tests specifically for your decorated functionality to catch regressions.
-
-
-### Common Decorator Patterns
-
-#### Adding Validations
-
-```ruby
-def self.prepended(base)
-  base.validates :custom_field, presence: true
-end
-```
-
-#### Adding Scopes
-
-```ruby
-def self.prepended(base)
-  base.scope :featured, -> { where(featured: true) }
-end
-```
-
-#### Adding Callbacks
-
-> **WARNING:** For callbacks that trigger side effects (syncing to external services, sending notifications, etc.), use [Events subscribers](../core-concepts/events.md) instead of decorator callbacks. Events are easier to test and won't break during Spree upgrades.
-
-**Decorator approach** (use only for simple, internal logic):
-
-```ruby
-def self.prepended(base)
-  base.before_save :normalize_name
-end
-
-def normalize_name
-  self.name = name.strip.titleize if name.present?
-end
-```
-
-**Events approach** (recommended for side effects): subscribe to `product.updated` and react in a `Spree::Subscriber` — no decorator, no callback coupling. The [Events & Webhooks tutorial](events.md) builds this out fully, including external-system sync (OMS, warehouse) and outbound webhooks.
-
-#### Adding Class Methods
-
-```ruby
-def self.prepended(base)
-  base.extend ClassMethods
-end
-
-module ClassMethods
-  def my_class_method
-    # Class method logic
-  end
-end
-```
-
-## Complete Files
-
-### Product Decorator
-
-```ruby app/models/spree/product_decorator.rb
-module Spree
-  module ProductDecorator
-    def self.prepended(base)
-      base.belongs_to :brand, class_name: 'Spree::Brand', optional: true
-    end
-  end
-
-  Product.prepend(ProductDecorator)
-end
-```
-
-### Brand Model (Updated)
-
-```ruby app/models/spree/brand.rb
-module Spree
-  class Brand < Spree::Base
-    has_many :products, class_name: 'Spree::Product', dependent: :nullify
-
-    has_one_attached :logo
-    has_rich_text :description
-
-    validates :name, presence: true
-  end
-end
-```
-
-> **INFO:** SEO features like slugs, meta titles, and FriendlyId are covered in the [Slugs](../core-concepts/slugs.md) documentation.
-
-### Spree Initializer Additions
-
-```ruby config/initializers/spree.rb
-# Permit brand_id in product params
-Spree::PermittedAttributes.product_attributes << :brand_id
-```
-
-**Spree 5.2+:**
-
-```ruby config/initializers/spree.rb
-    Rails.application.config.after_initialize do
-      # Add brand field to product form
-      Spree.admin.partials.product_form << 'spree/admin/products/brand_field'
-    end
-    ```
-
-  **Spree 5.1 and below:**
-
-```ruby config/initializers/spree.rb
-    # Add brand field to product form
-    Rails.application.config.spree_admin.product_form_partials << 'spree/admin/products/brand_field'
-    ```
-
-
-## Next Step
-
-Now that Brands are connected to Products, let's expose them through the Store API:
-
-- [6. API](api.md) — Create API endpoints for brands and extend the Product API response
-
-## Related Documentation
-
-- [Model Tutorial](model.md) - Creating the Brand model
-- [Admin Tutorial](admin.md) - Building the admin interface
-- [API Tutorial](api.md) - Exposing brands through the API
-- [Events & Webhooks tutorial](events.md) - Subscribers, custom events, and webhooks in the Brand storyline
-- [Events](../core-concepts/events.md) - Subscribe to model changes without decorators
-- [Webhooks](../core-concepts/webhooks.md) - HTTP callbacks for external integrations
-- [Decorators](../customization/decorators.md) - Full decorator reference
-- [Customization Overview](../customization/quickstart.md) - More customization patterns
-- [Products](../core-concepts/products.md) - Product model documentation

package/dist/developer/tutorial/sdk.md

@@ -1,170 +0,0 @@
----
-title: SDK
-description: Use the Spree TypeScript SDK to consume your custom Brand endpoints, fetch extended Product data, and surface the new resource in your headless storefront.
----
-
-In this tutorial, we'll use the `@spree/sdk` TypeScript SDK to consume the Brand API endpoints we created in the [API tutorial](api.md), and work with the extended Product data that now includes brand information.
-
-> **INFO:** This guide assumes you've completed the [API](api.md) tutorial and have the Brand endpoints running.
-
-## What We're Building
-
-By the end of this tutorial, you'll have:
-
-- Typed calls to your custom Brand endpoints using `client.request`
-- Extended Product types that include brand data
-- A working brand page example that ties it all together
-
-## How the SDK Works
-
-The `@spree/sdk` package provides a typed client for the Store API:
-
-```typescript
-import { createClient } from '@spree/sdk'
-
-const client = createClient({
-  baseUrl: 'https://api.mystore.com',
-  publishableKey: 'pk_YOUR_KEY',
-})
-
-// Built-in resources
-const products = await client.products.list()
-const product = await client.products.get('prod_86Rf07xd4z')
-const cart = await client.carts.create()
-```
-
-Under the hood, `createClient()` creates a request function that handles auth headers (`x-spree-api-key`), retries with exponential backoff, and URL building. All requests go through the base path `/api/v3/store`, so `client.products.list()` calls `GET /api/v3/store/products`.
-
-## Calling Custom Endpoints
-
-The client exposes a `request` method — the same function that powers all built-in resources. Use it to call any Store API endpoint, including custom ones:
-
-```typescript
-import { createClient } from '@spree/sdk'
-import type { PaginatedResponse } from '@spree/sdk'
-
-const client = createClient({
-  baseUrl: 'https://api.mystore.com',
-  publishableKey: 'pk_YOUR_KEY',
-})
-
-// Define your Brand type
-interface Brand {
-  id: string
-  name: string
-  slug: string | null
-  description: string | null
-  logo_url: string | null
-}
-
-// Call custom endpoints — paths are relative to /api/v3/store
-const brands = await client.request<PaginatedResponse<Brand>>('GET', '/brands')
-const nike = await client.request<Brand>('GET', '/brands/nike')
-```
-
-`client.request` has the same auth headers, retry logic, and locale/currency defaults as all built-in resources. The type parameter (`<Brand>`, `<PaginatedResponse<Brand>>`) gives you full type safety on the response.
-
-## Step 1: Define Brand Types
-
-Create a types file for your custom Brand resource:
-
-```typescript types/brand.ts
-import type { Product, PaginatedResponse } from '@spree/sdk'
-
-export interface Brand {
-  id: string
-  name: string
-  slug: string | null
-  description: string | null
-  logo_url: string | null
-}
-
-export interface ProductWithBrand extends Product {
-  brand_id: string | null
-  brand?: Brand
-}
-```
-
-## Step 2: Work with Extended Product Responses
-
-The Product serializer now includes `brand_id` and an expandable `brand` association.
-
-### Fetching Products with Brand Data
-
-```typescript
-import type { ProductWithBrand } from './types/brand'
-
-// Without expand — brand_id is included, brand object is not
-const product = await client.products.get('prod_86Rf07xd4z') as ProductWithBrand
-console.log(product.brand_id) // "brand_k5nR8xLq"
-console.log(product.brand)    // undefined
-
-// With expand — full brand object included
-const productWithBrand = await client.products.get(
-  'prod_86Rf07xd4z',
-  { expand: ['brand'] }
-) as ProductWithBrand
-console.log(productWithBrand.brand?.name) // "Nike"
-
-// Multiple expands
-const full = await client.products.get(
-  'prod_86Rf07xd4z',
-  { expand: ['brand', 'variants', 'categories'] }
-) as ProductWithBrand
-```
-
-### Filtering Products by Brand
-
-Ransack predicates work on whitelisted attributes and associations. The [API tutorial](api.md) shows how to register `brand_id` and `brand` via `Spree.ransack` — once that's done, you can filter:
-
-```typescript
-// Products from a specific brand
-const nikeProducts = await client.products.list({
-  brand_id_eq: 'brand_k5nR8xLq',
-})
-
-// Products matching brand name (requires Spree.ransack.add_association)
-const nikeProducts2 = await client.products.list({
-  brand_name_cont: 'nike',
-})
-```
-
-> **INFO:** Ransack predicates like `_eq`, `_cont`, `_gt`, `_lt` work on whitelisted attributes and associations. See [Search & Filtering](../core-concepts/search-filtering.md) for the full list.
-
-## Complete Example: Brand Page
-
-A real-world example combining everything — fetch a brand by slug and list its products:
-
-```typescript
-import { createClient } from '@spree/sdk'
-import type { PaginatedResponse } from '@spree/sdk'
-import type { Brand, ProductWithBrand } from './types/brand'
-
-const client = createClient({
-  baseUrl: 'https://api.mystore.com',
-  publishableKey: 'pk_YOUR_KEY',
-})
-
-// Fetch brand by slug
-const brand = await client.request<Brand>('GET', '/brands/nike')
-
-// Fetch products for this brand
-const products = await client.products.list({
-  brand_id_eq: brand.id,
-  sort: '-available_on',
-}) as PaginatedResponse<ProductWithBrand>
-
-// Render
-console.log(`${brand.name} — ${brand.description}`)
-console.log(`${products.meta.count} products`)
-products.data.forEach(p => {
-  console.log(`  ${p.name} — ${p.price.display}`)
-})
-```
-
-## Related Documentation
-
-- [API Tutorial](api.md) - Creating the Brand API endpoints
-- [SDK Overview](/sdk) - Full SDK documentation
-- [Search & Filtering](../core-concepts/search-filtering.md) - Ransack predicates and sorting
-- [Agentic Development](../agentic/overview.md) - Agent skills and the docs MCP server cover the SDK patterns used here

package/dist/developer/upgrades/2.0-to-2.1.md

@@ -1,46 +0,0 @@
----
-title: 2.0 to 2.1
-description: 'This guide covers upgrading a 2.0 Spree store, to a 2.1 store.'
----
-
-## Overview
-
-This guide has been written from the perspective of a blank Spree 2.0 store with no extensions.
-
-If you have extensions that your store depends on, you will need to manually verify that each of those extensions works within your 2.1 store once this upgrade is complete. Typically, extensions that are compatible with this version of Spree will have a 2-1-stable branch.
-
-This is the first Spree release that supports Rails 4 exclusively. Spree releases after this point will continue to support Rails 4 only.
-
-## Upgrade Rails
-
-For this Spree release, you will need to upgrade your Rails version to at least 4.0.0.
-
-It is recommended to read through the [Upgrading Ruby on Rails guide](http://guides.rubyonrails.org/upgrading_ruby_on_rails.html#upgrading-%20from-rails-3-2-to-rails-4-0) to learn what needs to be done for your application to migrate to Rails 4.
-
-```ruby
-gem 'rails', '~> 4.0'
-```
-
-## Upgrade Spree
-
-For best results, use the 2-1-stable branch from GitHub:
-
-```ruby
-gem 'spree', '~> 2.1'
-```
-
-Run `bundle update spree`.
-
-## Copy and run migrations
-
-Copy over the migrations from Spree (and any other engine) and run them using
-these commands:
-
-```bash
-    rake railties:install:migrations
-    rake db:migrate
-```
-
-## Read the release notes
-
-For information about changes contained with this release, please read the [2.1.0 Release Notes](https://github.com/spree/spree/releases/tag/v2.1.0).

package/dist/developer/upgrades/2.1-to-2.2.md

@@ -1,59 +0,0 @@
----
-title: 2.1 to 2.2
-section: upgrades
-description: 'This guide covers upgrading a 2.1 Spree store, to a 2.2 store.'
----
-
-## Overview
-
-This guide has been written from the perspective of a blank Spree 2.1 store with no extensions.
-
-If you have extensions that your store depends on, you will need to manually verify that each of those extensions works within your 2.2 store once this upgrade is complete. Typically, extensions that are compatible with this version of Spree will have a 2-2-stable branch.
-
-## Upgrade Rails
-
-For this Spree release, you will need to upgrade your Rails version to at least 4.0.6.
-
-```ruby
-gem 'rails', '~> 4.0.6'
-```
-
-## Upgrade Spree
-
-For best results, use the 2-2-stable branch from GitHub:
-
-```ruby
-gem 'spree', '~> 2.2'
-```
-
-Run `bundle update spree`.
-
-## Copy and run migrations
-
-Copy over the migrations from Spree (and any other engine) and run them using
-these commands:
-
-```bash
-rake railties:install:migrations
-```
-
-```bash
-rake db:migrate
-```
-
-## Read the release notes
-
-For information about changes contained with this release, please read the [2.2.0 Release Notes](http://guides.spreecommerce.org/release_notes/spree_2_2_0.html).
-
-### Rename assets
-
-As mentioned in the release notes, asset paths have changed. Change the references on the left, to the ones on the right:
-
-* `admin/spree_backend` => `spree/backend`
-* `store/spree_frontend` => `spree/frontend`
-
-This applies across the board on Spree, and may need to be done in your store's extensions.
-
-### Paperclip settings have been removed from master
-
-Please consult [this section](http://guides.spreecommerce.org/release_notes/spree_2_2_0.html#paperclip-settings-have-been-removed) of the release notes if you were using custom Paperclip settings. This will direct you what to do in that particular case.