@spree/docs 0.1.0

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

@@ -0,0 +1,38 @@
+---
+title: Multi-Store Setup
+sidebarTitle: Setup
+---
+
+## Root domain
+
+You need to set a wildcard `root_domain` on the store to enable multi-store setup
+
+```ruby
+Spree.root_domain = ENV.fetch('SPREE_ROOT_DOMAIN', 'lvh.me')
+```
+
+This will be used to generate the store URLs, eg. `store1.lvh.me`, `store2.lvh.me`, etc.
+
+`store1` part is the unique store `code` identifier, which is auto-generated based on the store name. You can change it in the admin panel in **Settings -> Domains**.
+
+> **INFO:** If you later change the `root_domain`, you will need to run:
+> 
+>   ```ruby
+  Spree::Store.all.each(&:save)
+  ```
+>   
+>   to update the store URLs.
+
+## Creating new stores
+
+After you restart your application, you will see a new option in the admin panel, under new item menu:
+
+![](/images/new_store_dropdown.png)
+
+You can also create a new store from the rails console:
+
+```ruby
+Spree::Store.create!(name: 'New Store')
+```
+
+This will create a new store with the given name, code and URL.

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

@@ -0,0 +1,41 @@
+---
+title: Spree Multi Tenant Configuration
+sidebarTitle: Configuration
+---
+
+Multi-tenant applications include additional configuration options. All configuration should be placed in `config/initializers/spree_multi_tenant.rb` file.
+
+### Root domain
+
+To make multi-tenant, you need a root/wildcard domain, eg. `*.example.com`. Tenant stores are usually accessed via subdomains, eg. `store1.example.com`, `store2.example.com`, etc.
+
+```bash
+Spree.root_domain = 'example.com'
+```
+
+Still your tenants will be able to add custom domains, eg. `myflowerstore.com` via the Spree admin panel. Tenant subdomains are used only for admin panel access.
+
+### App subdomain
+
+Application subdomains is used to access the application, eg. `app.example.com`. By default for existing tenants it will redirect them to their tenant subdomain, eg. `store1.example.com`. If you want, you can also use this as a tenant signup/store setup page, this is available under `app.example.com/tenants/new`.
+
+You can customize the app subdomain by:
+
+```ruby
+SpreeMultiTenant::Config[:app_subdomain] = 'admin'
+```
+
+This will change `app.example.com` to `admin.example.com`.
+
+### Emails
+
+Usually email providers, such as SendGrid, require emails to be send from a valid / verified email address, which will be your root domain.
+
+```ruby
+SpreeMultiTenant::Config[:mail_from_name] = ENV.fetch('MAIL_FROM_NAME', 'Your SaaS Name')
+SpreeMultiTenant::Config[:mail_from_address] = ENV.fetch('MAIL_FROM_ADDRESS', "support@#{Spree.root_domain}")
+```
+
+> **INFO:** `mail_from_name` is only used in admin emails, such as admin staff invitations, exports, etc. For consumer facing emails, this will be your tenant store name, eg. 'My Flower Store` (or whatever they set in the store settings).
+> 
+> Also, customer facing emails will use the tenant email address in `Reply-To` header.

package/dist/developer/multi-tenant/core-concepts.md

@@ -0,0 +1,75 @@
+---
+title: Multi-Tenant Core Concepts
+sidebarTitle: Core Concepts
+---
+
+## Tenant class
+
+The center of the multi-tenant architecture is the `Spree::Tenant` class. This is the highest level class in the multi-tenant system.
+
+Every tenanted model includes a `tenant_id` column. This is used to identify which tenant a record belongs to. It's row-level multi-tenancy.
+
+After creating a new tenant it will automatically create store and run [Spree seeds](https://github.com/spree/spree/tree/main/core/app/services/spree/seeds) to populate data such as countries, zones, tax rates, etc.
+
+## Tenanted models
+
+All models that are tenanted inherit from `SpreeMultiTenant::Base` class. `spree_multi_tenant` automatically sets the `Spree.base_class` to `SpreeMultiTenant::Base` so all standard Spree models will be tenanted (with an exclusion of `Spree::CustomDomain`).
+
+When creating a new model that you want to be tenanted remember to inherit from `SpreeMultiTenant::Base` and not from `Spree::Base` and add `tenant_id` column to the table, eg.
+
+```bash
+bin/rails g model Spree::NewModel tenant:references name:string --parent SpreeMultiTenant::Base
+```
+
+> **INFO:** You don't need to add `belongs_to :tenant` to the model, it's handled by gem.
+
+## Tenant selector
+
+By default the current tenant is selected based on the subdomain or `Spree::CustomDomain`. The selector works in tandem with the default [Spree::Stores::FindCurrent](https://github.com/spree/spree/blob/main/core/app/finders/spree/stores/find_current.rb) finder.
+
+First it finds the current store, and later sets the current tenant based on the store's `tenant_id`.
+
+Tenant record is accessible in views and controllers as `current_tenant`. In models you can access it via `SpreeMultiTenant.current_tenant`.
+
+> **INFO:** One tenant can have multiple stores. Calling `Spree::Store.default` will return the default store for the first tenant.
+
+## Code isolation
+
+All code run when `SpreeMultiTenant.current_tenant` is set will be executed in the context of the tenant, what that means:
+
+* all finder queries will always attach `tenant_id = <current_tenant.id>` to the query
+* all writes will automatically set `tenant_id` to the current tenant ID (you don't need to do it manually)
+
+> **WARNING:** [insert_all](https://api.rubyonrails.org/classes/ActiveRecord/Relation.html#method-i-insert_all) / [upsert_all](https://api.rubyonrails.org/classes/ActiveRecord/Relation.html#method-i-upsert_all) methods will require you to manually set `tenant_id` to the desired value.
+
+## Background jobs
+
+Background jobs enqueued when `SpreeMultiTenant.current_tenant` is set will be executed in the context of the tenant.
+
+## Enforce tenant context
+
+Sometimes when you're not sure if the tenant context is active you can use `SpreeMultiTenant.with_tenant` to enforce it, eg.
+
+```ruby
+SpreeMultiTenant.with_tenant(tenant) do
+  # all operations here will be executed in the context of the tenant
+end
+```
+
+## Excluding tenant context
+
+Sometimes you want to run a piece of code outside of the tenant context, for that you can use `SpreeMultiTenant.without_tenant`
+
+```ruby
+SpreeMultiTenant.without_tenant do
+  # all operations here will be executed outside of the tenant context
+end
+```
+
+## Command line
+
+When using `bin/rails console` or `bin/rails runner` you can set the tenant context by:
+
+```ruby
+SpreeMultiTenant.current_tenant = Spree::Store.find_by(code: 'my_store').tenant
+```

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

@@ -0,0 +1,96 @@
+---
+title: Spree Multi Tenant Installation
+sidebarTitle: Installation
+description: Learn how to setup a multi-tenant eCommerce (SaaS) with Spree
+---
+
+> **WARNING:** This installation instructions assume you have a clean Spree Starter installation and you've purchased the [Spree Enterprise Edition license](https://spreecommerce.org/pricing).
+>   
+>   For migrating existing application from single-tenant to multi-tenant, please contact us at [support@spreecommerce.org](mailto:support@spreecommerce.org).
+
+## Prerequisites
+
+* You need to be on Spree 5.1+, we recommend using [spree_starter](https://github.com/spree/spree_starter) as a base for your application
+* You need to have 2 environment variables set:
+  * `KEYGEN_ACCOUNT_ID`
+  * `KEYGEN_LICENSE_KEY`
+* We support both PostgreSQL and MySQL databases
+
+> **INFO:** Environment variables will be provided to you after purchasing the [Spree Enterprise Edition license](https://spreecommerce.org/pricing).
+
+> **WARNING:** You will need to add these environment variables to your CI/CD pipeline and production environments.
+
+## Customer User Class
+
+Please follow [Authentication](/docs/developer/customization/authentication) documentation to create a new user class.
+
+Now we will need to make slight adjustments to the generated user class so it can work in a multi-tenant environment.
+
+If you're using Devise, you will 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.
+
+Spree Multi-Tenant gem injects `SpreeMultiTenant::CustomerUserConcern` that handles that instead.
+
+## Admin User Class
+
+For our multi-tenant setup we will need a separate Admin user class. Our standard User class will be only used for customer accounts which will be isolated by tenant. 
+Admin user classes will be shared across tenants allowing them to manage multiple tenants from a single admin panel.
+
+Let's create a new model with Devise (unless you already have one):
+
+```bash
+rails g devise Spree::AdminUser
+```
+
+Replace the generated Devise code with the following:
+
+```ruby
+class Spree::AdminUser < Spree::Base
+  # Include default devise modules. Others available are:
+  # :confirmable, :lockable, :timeoutable, :trackable and :omniauthable
+  devise :database_authenticatable, :registerable,
+        :recoverable, :rememberable, :validatable
+
+  # Spree modules
+  include Spree::UserMethods
+end
+```
+
+If you already have a custom Admin user class, you can add the following code to it:
+
+```ruby
+  # Spree modules
+  include Spree::UserMethods
+```
+
+This will make sure that the Admin user class works well with Spree ecosystem.
+
+Register new model in `config/initializers/spree.rb`:
+
+```ruby
+Spree.admin_user_class = "Spree::AdminUser"
+```
+
+## Installing gems
+
+1. Add the following code to your `Gemfile`:
+
+    ```ruby
+    source "https://license:#{ENV['KEYGEN_LICENSE_KEY']}@rubygems.pkg.keygen.sh/#{ENV['KEYGEN_ACCOUNT_ID']}" do
+      gem 'spree_enterprise'
+      gem 'spree_multi_tenant'
+    end
+    ```
+
+2. Install gems:
+
+    ```bash
+    bundle install
+    ```
+
+3. Run generators:
+
+    ```bash
+    bundle exec rails g spree_enterprise:install && bundle exec rails g spree_multi_tenant:install
+    ```
+
+    > **INFO:** This will copy and run migrations for `spree_enterprise` and `spree_multi_tenant` gems.

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

@@ -0,0 +1,20 @@
+---
+title: Building a Multi-Tenant Spree Application
+sidebarTitle: Quickstart
+---
+
+Spree out of the box is a single-tenant application. You can have multiple stores on the same instance of Spree, but they share the same products, admin user accounts and other resources.
+Multi-Store Spree setup is recommended for running multiple brands or multiple language versions of the same brand on the same instance.
+
+If you want to have a true multi-tenant application, you will need to purchase [Enterprise Edition license](https://spreecommerce.org/pricing) which includes `spree_multi_tenant` gem providing full multi-tenant support.
+
+## Multi-Store vs Multi-Tenant
+
+To sum it up:
+
+* Multi-Store setup is recommended for running multiple brands or multiple language versions of the same store
+* Multi-Tenant allows you to create a SaaS application with multiple tenants, each of them with their own Spree instance
+
+## Setup SaaS application
+
+[Follow the installation instructions](/developer/multi-tenant/installation) to setup a multi-tenant Spree application.

package/dist/developer/multi-vendor/installation.md

@@ -0,0 +1,45 @@
+---
+title: Spree Multi Vendor Installation
+sidebarTitle: Installation
+description: Learn how to setup a multi-vendor marketplace with Spree
+---
+
+> **WARNING:** This installation instructions assume you have purchased the [Spree Enterprise Edition license](https://spreecommerce.org/pricing).
+
+## Prerequisites
+
+* You need to be on Spree 5.1+, we recommend using [spree_starter](https://github.com/spree/spree_starter) as a base for your application
+* You need to have 2 environment variables set:
+  * `KEYGEN_ACCOUNT_ID`
+  * `KEYGEN_LICENSE_KEY`
+* We support both PostgreSQL and MySQL databases
+* Redis/Valkey for background jobs
+
+> **INFO:** Environment variables will be provided to you after purchasing the [Spree Enterprise Edition license](https://spreecommerce.org/pricing).
+
+> **WARNING:** You will need to add these environment variables to your CI/CD pipeline and production environments.
+
+## Installing gems
+
+1. Add the following code to your `Gemfile`:
+
+    ```ruby
+    source "https://license:#{ENV['KEYGEN_LICENSE_KEY']}@rubygems.pkg.keygen.sh/#{ENV['KEYGEN_ACCOUNT_ID']}" do
+      gem 'spree_enterprise'
+      gem 'spree_multi_vendor'
+    end
+    ```
+
+2. Install gems:
+
+    ```bash
+    bundle install
+    ```
+
+3. Run generators:
+
+    ```bash
+    bundle exec rails g spree_enterprise:install && bundle exec rails g spree_multi_vendor:install
+    ```
+
+    > **INFO:** This will copy and run migrations for `spree_enterprise` and `spree_multi_vendor` gems.

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

@@ -0,0 +1,17 @@
+---
+title: Building a Multi-Vendor Marketplace with Spree
+sidebarTitle: Quickstart
+---
+
+If you want to have a true multi-vendor marketplace, you will need to purchase [Enterprise Edition license](https://spreecommerce.org/pricing) which includes `spree_multi_vendor` gem providing full multi-vendor support.
+
+## What is included in `spree_multi_vendor`
+
+1. **Ability to invite and manage vendors**, their products and orders
+2. Full fledged **vendor dashboard** where vendors can self-serve orders, products, manage their team, etc.
+3. White-label **Shopify Sales Channel application** allowing vendors to connect their Shopify stores, import products, shipping rates and receive orders to fulfill them like a regular order in their Shopify store.
+4. White-label **WooCommerce application** allowing vendors to connect their WooCommerce stores, import products, shipping rates and receive orders to fulfill them like a regular order in their WooCommerce store
+5. **Stripe Connect** integration allowing vendors to receive payments directly to their Stripe accounts, split payments between marketplace and vendors, automated payouts and more
+6. **Multi-party checkout** allowing customers to checkout with multiple vendors, split payments between them and receive separate invoices for each vendor
+7. **Flexible permission system** to tailor the marketplace to your needs (eg. disable/enable vendor panel features)
+8. **Vendor API** endpoints to allow vendors to manage their products, orders, etc.

package/dist/developer/sdk/admin/quickstart.md

@@ -0,0 +1,22 @@
+---
+title: Admin API
+description: Manage your store programmatically with the Spree Admin SDK
+---
+
+> **INFO:** The Admin API SDK is coming soon. The `client.admin` namespace is ready and will provide full access to administrative endpoints for managing products, orders, customers, and store settings.
+
+## Preview
+
+```typescript
+import { createClient } from '@spree/sdk';
+
+const client = createClient({
+  baseUrl: 'https://api.mystore.com',
+  secretKey: 'spree_sk_xxx', // Admin API requires a secret key
+});
+
+// Admin endpoints will be available under client.admin.*
+// client.admin.products.list()
+// client.admin.orders.list()
+// client.admin.customers.list()
+```

package/dist/developer/sdk/authentication.md

@@ -0,0 +1,89 @@
+---
+title: Authentication
+description: Authentication modes and guest checkout with the Spree SDK
+---
+
+The SDK supports multiple authentication modes depending on your use case. For a full overview of the API authentication methods, see the [Store API Authentication](/api-reference/store-api/authentication) reference.
+
+## Publishable Key Only (Guest/Public Access)
+
+Use a publishable API key for public endpoints like browsing products:
+
+```typescript
+import { createClient } from '@spree/sdk'
+
+const client = createClient({
+  baseUrl: 'http://localhost:3000',
+  publishableKey: 'spree_pk_xxx',
+})
+```
+
+
+```typescript
+// Public endpoints work without user authentication
+const products = await client.products.list()
+```
+
+## Publishable Key + JWT (Authenticated Customer)
+
+For authenticated customer actions like viewing orders or managing addresses:
+
+```typescript
+// Login to get a JWT token
+const { token, user } = await client.auth.login({
+  email: 'customer@example.com',
+  password: 'password123',
+})
+
+// Use the token for authenticated requests
+const orders = await client.customer.orders.list({}, { token })
+```
+
+
+```typescript
+// Refresh token when needed
+const newTokens = await client.auth.refresh({ token })
+```
+
+## Register New Customer
+
+```typescript
+const { token, user } = await client.customers.create({
+  email: 'new@example.com',
+  password: 'password123',
+  password_confirmation: 'password123',
+  first_name: 'John',
+  last_name: 'Doe',
+})
+```
+
+## Guest Checkout
+
+For guest checkout, use the `token` returned when creating a cart. The SDK automatically sends it via the `x-spree-token` header:
+
+```typescript
+// Create a cart (guest)
+const cart = await client.carts.create()
+
+// Use spreeToken for all cart and checkout operations
+const options = { spreeToken: cart.token }
+
+// Add items
+await client.carts.items.create(cart.id, {
+  variant_id: 'variant_abc123',
+  quantity: 1,
+}, options)
+```
+
+
+```typescript
+const options = { spreeToken: cart.token }
+
+// Update cart with email
+await client.carts.update(cart.id, {
+  email: 'guest@example.com',
+}, options)
+
+// Complete checkout
+await client.carts.complete(cart.id, options)
+```

package/dist/developer/sdk/configuration.md

@@ -0,0 +1,225 @@
+---
+title: Configuration
+description: Localization, error handling, TypeScript types, and custom fetch
+---
+
+## Localization & Currency
+
+Pass locale and currency headers with any request. For full details, see the [Localization](/api-reference/store-api/localization) reference.
+
+```typescript
+// Set locale and currency per request
+const products = await client.products.list({}, {
+  locale: 'fr',
+  currency: 'EUR',
+  country: 'FR',
+})
+```
+
+
+```typescript
+// Works with all endpoints
+const category = await client.categories.get('clothing/shirts', {
+  expand: ['ancestors'],
+}, {
+  locale: 'de',
+  currency: 'EUR',
+})
+```
+
+## Error Handling
+
+```typescript
+import { SpreeError } from '@spree/sdk';
+
+try {
+  await client.products.get('non-existent');
+} catch (error) {
+  if (error instanceof SpreeError) {
+    console.log(error.code);    // 'record_not_found'
+    console.log(error.message); // 'Product not found'
+    console.log(error.status);  // 404
+    console.log(error.details); // Validation errors (if any)
+  }
+}
+```
+
+## Custom Fetch
+
+You can provide a custom fetch implementation:
+
+```typescript
+import { createClient } from '@spree/sdk';
+
+const client = createClient({
+  baseUrl: 'https://api.mystore.com',
+  publishableKey: 'spree_pk_xxx',
+  fetch: customFetchImplementation,
+});
+```
+
+## Monetary Amounts
+
+All monetary values in the API are returned as **strings** (e.g., `"29.99"`, `"0.0"`), not numbers. This preserves decimal precision and avoids floating-point rounding issues.
+
+```typescript
+const order = await client.orders.get('or_abc123', {}, { token });
+
+// Monetary fields are strings
+order.total;         // "129.99"
+order.item_total;    // "99.99"
+order.delivery_total;    // "10.00"
+order.tax_total;     // "20.00"
+
+// Display fields include currency formatting
+order.display_total; // "$129.99"
+
+// Convert to number when needed for calculations
+const total = parseFloat(order.total);
+```
+
+This applies to all monetary fields across all types: `Order`, `LineItem`, `Fulfillment`, `Payment`, `GiftCard`, `Price`, etc.
+
+## TypeScript Support
+
+The SDK includes full TypeScript support with generated types from the API serializers:
+
+```typescript
+import type {
+  Product,
+  Order,
+  Cart,
+  Variant,
+  Category,
+  LineItem,
+  Address,
+  Customer,
+  PaginatedResponse,
+} from '@spree/sdk';
+
+// All responses are fully typed
+const products: PaginatedResponse<Product> = await client.products.list();
+const category: Category = await client.categories.get('clothing');
+```
+
+## Available Types
+
+All types are exported as unprefixed names (e.g., `Product`, `Order`). Legacy `Store*` prefixed aliases (e.g., `StoreProduct`) are still available for backward compatibility.
+
+### Core Types
+- `Product` - Product data
+- `Variant` - Variant data
+- `Cart` - Cart data (uses `cart_` prefixed IDs)
+- `Order` - Completed order data (uses `or_` prefixed IDs)
+- `LineItem` - Line item in cart
+- `Category` - Category
+- `Country` - Country with states
+- `State` - State/province
+- `Address` - Customer address
+- `Customer` - Customer profile
+- `Market` - Market configuration (currency, locales, countries)
+
+### Commerce Types
+- `Payment` - Payment record
+- `PaymentMethod` - Payment method
+- `PaymentSession` - Provider-agnostic payment session
+- `Fulfillment` - Fulfillment record
+- `DeliveryRate` - Delivery rate option
+- `DeliveryMethod` - Delivery method
+- `CreditCard` - Saved credit card
+- `GiftCard` - Gift card
+- `Discount` - Discount applied to a cart or order
+
+### Product Types
+- `Media` - Product media (images, videos)
+- `Price` - Price data
+- `OptionType` - Option type (e.g., Size, Color)
+- `OptionValue` - Option value (e.g., Small, Red)
+- `DigitalLink` - Digital download link
+- `Metafield` - Custom metafield data
+
+### Wishlist Types
+- `Wishlist` - Wishlist
+- `WishlistItem` - Wishlist item
+
+### Client Types
+- `Client` - Main client interface
+- `StoreClient` - Store API client class
+- `ClientConfig` - Client configuration
+- `RequestOptions` - Per-request options
+- `RetryConfig` - Retry behavior configuration
+
+### Utility Types
+- `PaginatedResponse<T>` - Paginated API response
+- `ListResponse<T>` - List API response
+- `AuthTokens` - JWT tokens from login
+- `AddressParams` - Address input parameters
+- `UpdateCartParams` - Cart update parameters
+- `CreatePaymentParams` - Direct payment creation parameters
+- `CreatePaymentSessionParams` - Payment session creation parameters
+- `UpdatePaymentSessionParams` - Payment session update parameters
+- `CompletePaymentSessionParams` - Payment session completion parameters
+- `ProductFiltersResponse` - Product filters response
+- `CheckoutRequirement` - Checkout requirement (`{ step, field, message }`)
+
+## Extending Types
+
+All generated SDK types are TypeScript `interface`s, which means you can extend them via [declaration merging](https://www.typescriptlang.org/docs/handbook/declaration-merging.html) when you customize API serializers on the backend.
+
+### Example: Adding a Brand to Products
+
+If you've customized the `ProductSerializer` in your app to include a `brand_id` attribute:
+
+```ruby
+# app/serializers/my_store/product_serializer.rb
+module MyStore
+  class ProductSerializer < Spree::Api::V3::ProductSerializer
+    typelize brand_id: :string
+
+    attribute :brand_id do |product|
+      product.brand&.prefixed_id
+    end
+  end
+end
+
+# config/initializers/spree.rb
+Spree.api.product_serializer = MyStore::ProductSerializer
+```
+
+You can extend the SDK type in your frontend code so TypeScript knows about the new field:
+
+```typescript
+// types/spree.d.ts
+declare module '@spree/sdk' {
+  interface Product {
+    brand_id: string;
+  }
+}
+```
+
+Now `brand_id` is available on every `Product` across your app — no type casting needed:
+
+```typescript
+const products = await client.products.list();
+products.data.forEach((product) => {
+  console.log(product.brand_id); // fully typed
+});
+```
+
+### Extending Zod Schemas
+
+If you use the SDK's Zod schemas for runtime validation, extend them with `.extend()`:
+
+```typescript
+import { z } from 'zod';
+import { ProductSchema } from '@spree/sdk/zod';
+
+const MyProductSchema = ProductSchema.extend({
+  brand_id: z.string(),
+});
+
+// Use for runtime validation
+const product = MyProductSchema.parse(apiResponse);
+```
+
+> **NOTE:** Declaration merging only affects TypeScript types (compile-time). Zod schemas perform runtime validation and must be extended separately if you need validation of custom fields.