@spree/docs 0.1.0

package/dist/developer/customization/dependencies.md

@@ -0,0 +1,232 @@
+---
+title: Dependencies
+section: customization
+---
+
+## Overview
+
+With Dependencies, you can easily replace parts of Spree core with your custom code. You can replace [Services](https://github.com/spree/spree/tree/master/core/app/services/spree), CanCanCan Abilities (used for [Permissions](permissions)), and [API Serializers](https://github.com/spree/spree/tree/master/api/app/serializers/spree/v2) (used for generating JSON API responses).
+
+## Application (global) customization
+
+This will change every aspect of the application (both APIs, Admin Panel, and Storefront).
+
+In your `config/initializers/spree.rb` file, you can set the following:
+
+```ruby
+Spree.cart_add_item_service = MyAddToCartService
+```
+
+or using the block syntax:
+
+```ruby
+Spree.dependencies do |dependencies|
+  dependencies.cart_add_item_service = MyAddToCartService
+end
+```
+
+Now let's create your custom service.
+
+```bash
+mkdir -p app/services && touch app/services/my_add_to_cart_service.rb
+```
+
+And add the following code to it:
+
+```ruby
+class MyAddToCartService < Spree::Cart::AddItem
+  def call(order:, variant:, quantity: nil, public_metadata: {}, private_metadata: {}, options: {})
+    ApplicationRecord.transaction do
+      run :add_to_line_item
+      run Spree.cart_recalculate_service
+      run :update_in_external_system
+    end
+  end
+
+  private
+
+  def update_in_external_system(new_order_line_item)
+    # Your custom logic here
+  end
+end
+```
+
+This code will:
+
+1. Inherit from `Spree::Cart::AddItem`
+2. Override the `call` method to add your custom logic
+3. Call `run :add_to_line_item` to add the item to the cart
+4. Call `run Spree.cart_recalculate_service` to recalculate the cart (returns the resolved class)
+5. Call `run :update_in_external_system` to execute your custom logic, eg. updating Order in an external system such as ERP
+
+## Using dependencies in your code
+
+When you need to use a dependency in your code, you can access it directly via the `Spree` module:
+
+```ruby
+# Returns the resolved class (not a string)
+Spree.cart_add_item_service.call(order: order, variant: variant, quantity: 1)
+
+# For API dependencies, use the Spree.api accessor
+Spree.api.storefront_cart_serializer.new(order).serializable_hash
+```
+
+## Controller level customization
+
+If you need to replace [serializers](https://github.com/jsonapi-serializer/jsonapi-serializer) or Services in a specific API endpoint you can create a [code decorator](/developer/customization/decorators):
+
+```bash
+mkdir -p app/controllers/spree && touch app/controllers/spree/cart_controller_decorator.rb
+```
+
+and add the following code to it:
+
+```ruby
+module Spree
+  module CartControllerDecorator
+    def resource_serializer
+      MyNewAwesomeCartSerializer
+    end
+
+    def add_item_service
+      MyNewAwesomeAddItemToCart
+    end
+  end
+
+  CartController.prepend(CartControllerDecorator)
+end
+```
+
+This will change the serializer in this API endpoint to `MyNewAwesomeCartSerializer` and also it will swap the default `add_item_service` to `MyNewAwesomeAddItemToCart`.
+
+Different API endpoints can have different dependency injection points. You can review their [source code](https://github.com/spree/spree/tree/master/api/app/controllers/spree/api/v2) to see what you can replace.
+
+## API level customization
+
+Storefront API and Platform API have separate Dependencies injection points so you can easily customize one without touching the other.
+
+In your Spree initializer (`config/initializers/spree.rb`) please add:
+
+```ruby
+Spree.api.storefront_cart_serializer = MyNewAwesomeCartSerializer
+Spree.api.storefront_cart_add_item_service = MyNewAwesomeAddItemToCart
+```
+
+This will swap the default Cart serializer and Add Item to Cart service for your custom ones within all Storefront API endpoints that use those classes.
+
+You can mix and match both global and API-level customizations:
+
+```ruby
+Spree.cart_add_item_service = MyNewAwesomeAddItemToCart
+Spree.api.storefront_cart_add_item_service = AnotherAddItemToCart
+```
+
+The second line will have precedence over the first one, and the Storefront API will use `AnotherAddItemToCart` and the rest of the application will use `MyNewAwesomeAddItemToCart`.
+
+## Debugging dependencies
+
+Spree provides rake tasks to help you debug and inspect dependencies:
+
+### List all dependencies
+
+```bash
+bin/rake spree:dependencies:list
+```
+
+This will output all dependencies with their current values:
+
+```
+[CORE]
+cart_add_item_service           Spree::Cart::AddItem
+cart_create_service             Spree::Cart::Create
+cart_recalculate_service        Spree::Cart::Recalculate [OVERRIDDEN]
+...
+
+[API]
+storefront_cart_serializer      Spree::V2::Storefront::CartSerializer
+storefront_cart_add_item_service  MyApp::CartAddItem [OVERRIDDEN]
+...
+```
+
+You can use `grep` to filter results:
+
+```bash
+bin/rake spree:dependencies:list | grep cart
+```
+
+### Show only overridden dependencies
+
+```bash
+bin/rake spree:dependencies:overrides
+```
+
+This shows only the dependencies that have been customized, along with their original and current values:
+
+```
+[Core OVERRIDES]
+cart_recalculate_service  Spree::Cart::Recalculate -> MyApp::CartRecalculate (config/initializers/spree.rb:15)
+
+[API OVERRIDES]
+storefront_cart_add_item_service  Spree::Cart::AddItem -> MyApp::CartAddItem (config/initializers/spree.rb:20)
+```
+
+### Validate all dependencies
+
+```bash
+bin/rake spree:dependencies:validate
+```
+
+This validates that all dependencies can be resolved to valid classes. If any dependency points to a non-existent class, it will report an error:
+
+```
+..........F.........
+1 invalid dependencies:
+  [Core] cart_add_item_service: uninitialized constant NonExistentClass
+```
+
+## Programmatic introspection
+
+You can also inspect dependencies programmatically:
+
+```ruby
+# Check all current values
+Spree::Dependencies.current_values
+# => [{name: :cart_add_item_service, current: MyApp::CartAddItem, default: 'Spree::Cart::AddItem', overridden: true}, ...]
+
+# Check if a specific dependency is overridden
+Spree::Dependencies.overridden?(:cart_add_item_service)
+# => true
+
+# Get override information (where it was set)
+Spree::Dependencies.override_info(:cart_add_item_service)
+# => {value: MyApp::CartAddItem, source: "config/initializers/spree.rb:15", set_at: 2024-01-15 10:30:00}
+
+# Validate all dependencies resolve to valid classes
+Spree::Dependencies.validate!
+# => true (or raises Spree::DependencyError)
+```
+
+## Backwards compatibility
+
+The legacy string-based syntax is still supported for backwards compatibility:
+
+```ruby
+# Legacy syntax (still works)
+Spree::Dependencies.cart_add_item_service = 'MyAddToCartService'
+result = Spree::Dependencies.cart_add_item_service.constantize
+
+# New syntax (recommended)
+Spree.cart_add_item_service = MyAddToCartService
+result = Spree.cart_add_item_service
+```
+
+Both syntaxes can coexist, but the new syntax is recommended as it's more concise and provides better error messages at assignment time.
+
+## Default values
+
+Default values can be easily checked by:
+
+1. Using the rake task: `bin/rake spree:dependencies:list`
+2. Looking at the source code:
+   * [Application (global) dependencies](https://github.com/spree/spree/blob/main/core/lib/spree/core/dependencies.rb)
+   * [API level dependencies](https://github.com/spree/spree/blob/main/api/lib/spree/api/dependencies.rb)

package/dist/developer/customization/emails.md

@@ -0,0 +1,21 @@
+---
+title: Emails
+---
+
+> **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 offers an emails preview generator for development purposes. To generate them, use the command:
+
+```bash
+bin/rails g spree:emails:install
+```
+
+After that, start the rails server locally and go to: `localhost:3000/rails/mailers`
+
+(it requires a seeded development database in order to work properly)

package/dist/developer/customization/extensions.md

@@ -0,0 +1,92 @@
+---
+title: Extensions
+description: >-
+  Extensions provide additional features and integrations for your Spree
+  application. Here's a list of the most popular ones.
+---
+
+> **TIP:** For officially supported 3rd party integrations, please go to [Integrations](/integrations) page.
+
+<details>
+<summary>Customer Service</summary>
+
+- [Gladly](https://github.com/upsidelab/spree_gladly) — Allows you to connect your Spree store with [Gladly](https://www.gladly.com/) service. It allows Gladly agents to see basic information about Spree customers and their orders.
+
+</details>
+
+
+  <details>
+<summary>Internationalization</summary>
+
+- [Spree I18n](https://github.com/spree-contrib/spree_i18n) — Spree I18n is a gem that provides a way to translate Spree applications into multiple languages. It allows you to translate the UI and have different translations for product descriptions, taxons, etc to improve conversions and customer satisfaction.
+    - [Flow Commerce](https://github.com/mejuri-inc/flowcommerce_spree) — Integration with Flow Commerce API for cross border selling.
+
+</details>
+
+  <details>
+<summary>Order Management</summary>
+
+- [Print Invoice](https://github.com/spree-contrib/spree_print_invoice) — Create a PDF invoice for Spree orders.
+
+</details>
+
+
+  <details>
+<summary>Marketing</summary>
+
+- [MailChimp E-Commerce](https://github.com/spree-contrib/spree_mailchimp_ecommerce) — Full Spree Mailchimp E-Commerce integration.
+
+</details>
+
+
+  <details>
+<summary>Products</summary>
+
+- [Volume Pricing](https://github.com/spree-contrib/spree_volume_pricing) — Spree extension which supports sales volume-based pricing quantity discounts.
+    - [Products Q&A](https://github.com/TruemarkDev/spree_products_qa) — Q&A Sections for products. Logged in users can ask a question, and then admins are able to answer it. All answered and accepted questions are displayed on a product page.
+
+</details>
+
+
+  <details>
+<summary>Search</summary>
+
+- [SearchKick](https://github.com/spree-contrib/spree_searchkick) — Adds Elasticsearch integration to Spree, powered by [searchkick](https://github.com/ankane/searchkick) gem enabling full-text searching and advanced product filtering.
+
+</details>
+
+
+  <details>
+<summary>Shipping</summary>
+
+- [EasyPost](https://github.com/ShopFelixGray/spree_easypost) — This is an extension to integrate Easy Post into Spree.
+    - [ShipStation](https://github.com/MatthewKennedy/spree_shipstation) — Connect your Spree store with ShipStation, allowing ShipStation to pull shipments from your store, and when a shipment is sent, update the order with a tracking number and mark it as shipped.
+
+</details>
+
+
+  <details>
+<summary>Social</summary>
+
+- [Social Login](https://github.com/spree-contrib/spree_social) — Login or signup via Facebook, Twitter, Amazon and other.
+    - [Reviews](https://github.com/spree-contrib/spree_reviews) — Straightforward review/rating functionality.
+
+</details>
+
+
+  <details>
+<summary>Tax Calculation</summary>
+
+- [Avatax](https://github.com/spree-contrib/spree_avatax_official) — The new officially certified Spree Avatax Avalara extension.
+    - [TaxJar](https://github.com/spree-contrib/spree_taxjar) — Spree Taxjar is a US sales tax extension for Spree using the Taxjar service.
+
+</details>
+
+
+  <details>
+<summary>Upselling</summary>
+
+- [Product Assembly](https://github.com/spree-contrib/spree-product-assembly) — Adds the ability to make product bundles.
+    - [Related Products](https://github.com/spree-contrib/spree_related_products) — Possible uses: Accessories, Cross Sells, Up Sells, Compatible Products, Replacement Products, Warranty & Support Products.
+
+</details>

package/dist/developer/customization/metadata.md

@@ -0,0 +1,236 @@
+---
+title: Metadata
+---
+
+## Overview
+
+Metadata provides simple, unstructured key-value storage on Spree resources — similar to [Stripe's metadata](https://docs.stripe.com/api/metadata). It's ideal for storing integration IDs, tracking data, or any arbitrary information that doesn't need validation or admin UI.
+
+Metadata is **write-only** in the Store API — you can set it when creating or updating resources, but it is never returned in Store API responses. It is visible in Admin API responses for administrative use.
+
+> **INFO:** For structured, type-safe custom attributes with admin UI support, use [Metafields](/developer/core-concepts/metafields) instead.
+
+## Store API
+
+### Cart creation
+
+Set metadata when creating a new cart:
+
+```bash
+POST /api/v3/store/carts
+Content-Type: application/json
+
+{
+  "metadata": {
+    "source": "mobile_app",
+    "campaign": "summer_sale"
+  }
+}
+```
+
+```typescript
+// @spree/sdk
+const cart = await client.carts.create({
+  metadata: { source: 'mobile_app', campaign: 'summer_sale' }
+})
+
+// @spree/next
+const cart = await getOrCreateCart({ source: 'mobile_app' })
+```
+
+### Adding items
+
+Set metadata when adding items to the cart:
+
+```bash
+POST /api/v3/store/carts/:cart_id/items
+Content-Type: application/json
+
+{
+  "variant_id": "variant_k5nR8xLq",
+  "quantity": 1,
+  "metadata": {
+    "gift_note": "Happy Birthday!",
+    "engraving": "J.D."
+  }
+}
+```
+
+```typescript
+const order = await client.carts.items.create(cartId, {
+  variant_id: 'variant_k5nR8xLq',
+  quantity: 1,
+  metadata: { gift_note: 'Happy Birthday!' },
+})
+```
+
+### Updating items
+
+Metadata is **merged** with existing values on update. Set a key to `null` to remove it.
+
+```bash
+PATCH /api/v3/store/carts/:cart_id/items/:id
+Content-Type: application/json
+
+{
+  "metadata": {
+    "engraving": "A.B.",
+    "gift_note": null
+  }
+}
+```
+
+You can update metadata without changing quantity, or update both at once:
+
+```typescript
+// Metadata only
+await client.carts.items.update(cartId, lineItemId, {
+  metadata: { engraving: 'A.B.' },
+})
+
+// Both quantity and metadata
+await client.carts.items.update(cartId, lineItemId, {
+  quantity: 3,
+  metadata: { gift_note: 'Happy Birthday!' },
+})
+```
+
+### Updating carts
+
+```bash
+PATCH /api/v3/store/carts/:id
+Content-Type: application/json
+
+{
+  "metadata": {
+    "utm_source": "google",
+    "utm_campaign": "summer_sale"
+  }
+}
+```
+
+```typescript
+await client.carts.update(cartId, {
+  metadata: { utm_source: 'google' },
+}, { spreeToken })
+```
+
+## Admin API
+
+Metadata is **readable** in Admin API responses on orders and line items:
+
+```json
+{
+  "id": "or_m3Rp9wXz",
+  "number": "R123456",
+  "metadata": {
+    "source": "mobile_app",
+    "utm_campaign": "summer_sale"
+  },
+  "items": [
+    {
+      "id": "li_x8Kp2qWz",
+      "metadata": {
+        "gift_note": "Happy Birthday!"
+      }
+    }
+  ]
+}
+```
+
+When there is no metadata, the field is `null`.
+
+## Ruby / Backend
+
+### Reading and writing
+
+Every model that includes `Spree::Metadata` has a `metadata` accessor (alias for `private_metadata`):
+
+```ruby
+order = Spree::Order.find_by!(number: 'R123456')
+
+# Write
+order.metadata = { 'source' => 'mobile_app' }
+order.save!
+
+# Read
+order.metadata['source'] # => "mobile_app"
+
+# Merge
+order.metadata = order.metadata.merge('campaign' => 'summer')
+order.save!
+```
+
+### Querying
+
+```ruby
+# Find orders with specific metadata value (PostgreSQL)
+Spree::Order.where("private_metadata->>'source' = ?", "mobile_app")
+
+# Check for key existence
+Spree::Order.where("private_metadata ? 'source'")
+```
+
+## Merge semantics
+
+Metadata updates use **merge semantics** — existing keys are preserved, new keys are added, and keys set to `null` are removed. This matches [Stripe's behavior](https://docs.stripe.com/api/metadata).
+
+```
+# Initial metadata
+{ "source": "mobile_app", "campaign": "summer" }
+
+# Update with
+{ "campaign": "winter", "new_key": "value" }
+
+# Result
+{ "source": "mobile_app", "campaign": "winter", "new_key": "value" }
+```
+
+## Metadata vs Metafields
+
+| | Metadata | [Metafields](/developer/core-concepts/metafields) |
+|---|---|---|
+| **Use case** | Integration data, tracking, simple key-value | Structured custom attributes with admin UI |
+| **Validation** | None | Type-specific (text, number, boolean, JSON) |
+| **Visibility** | Write-only in Store API, readable in Admin API | Configurable (front-end, back-end, both) |
+| **Admin UI** | Viewable in JSON preview | Full admin management |
+| **Schema** | Schemaless JSON | Defined via MetafieldDefinitions |
+| **API pattern** | Stripe-style flat key-value | Shopify-style typed resources |
+
+### When to use metadata
+
+- Storing external system IDs (e.g., Stripe payment intent ID, ERP order ID)
+- Tracking attribution data (UTM parameters, referral source)
+- Passing context from the storefront that doesn't need validation
+- Any write-and-forget data that only needs to be read by backend systems
+
+### When to use metafields
+
+- Custom product specifications shown to customers
+- Admin-managed fields with validation
+- Data that needs to appear in the admin UI
+- Querying/filtering by custom attributes
+
+## Supported resources
+
+All models that include the `Spree::Metadata` concern support metadata. This includes all core models: Orders, Line Items, Products, Variants, Taxons, Payments, Shipments, and more.
+
+The Store API currently supports writing metadata on:
+
+- **Carts** — on creation and update (`POST /api/v3/store/carts`, `PATCH /api/v3/store/carts/:id`)
+- **Items** — on create and update (`POST/PATCH /api/v3/store/carts/:id/items`)
+
+## Migration from public_metadata
+
+The `public_metadata` column is deprecated. Metadata is no longer returned in Store API responses. If you were using `public_metadata` for data that needs to be visible to customers, migrate to [Metafields](/developer/core-concepts/metafields) with `display_on: 'both'`.
+
+```ruby
+# Before (deprecated)
+order.public_metadata = { 'gift_message' => 'Happy Birthday!' }
+
+# After — use metadata for write-only storage
+order.metadata = { 'gift_message' => 'Happy Birthday!' }
+
+# After — use metafields for customer-visible structured data
+order.set_metafield('custom.gift_message', 'Happy Birthday!')
+```