@spree/docs 0.1.0

package/dist/developer/core-concepts/search-filtering.md

@@ -0,0 +1,237 @@
+---
+title: Search & Filtering
+description: "Search, filter, and sort products and other resources via the Store API"
+---
+
+## Overview
+
+Spree provides powerful search, filtering, and sorting capabilities for products and other resources. The Store API supports:
+
+- Full-text search across product names, descriptions, and SKUs
+- Attribute-based filtering (price range, availability, stock status)
+- Category and taxon filtering
+- Faceted search with filter counts
+- Flexible sorting options
+
+## Product Search
+
+Use the `search` parameter for full-text search across product fields:
+
+
+```typescript SDK
+const { data: products } = await client.products.list({
+  search: 'tote bag',
+  limit: 12,
+})
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/products?q[search]=tote+bag&limit=12' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+## Filtering Products
+
+### By Price Range
+
+
+```typescript SDK
+const { data: products } = await client.products.list({
+  price_gte: 20,
+  price_lte: 100,
+})
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/products?q[price_gte]=20&q[price_lte]=100' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+### By Availability
+
+
+```typescript SDK
+const { data: products } = await client.products.list({
+  in_stock: true,
+})
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/products?q[in_stock]=true' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+### By Category
+
+
+```typescript SDK
+// Products in a specific category
+const { data: products } = await client.categories.products.list('clothing/shirts', {
+  limit: 12,
+})
+
+// Or filter by category ID
+const { data: products } = await client.products.list({
+  categories_id_eq: 'ctg_xxx',
+})
+```
+
+```bash cURL
+# Products in a category
+curl 'https://api.mystore.com/api/v3/store/categories/clothing/shirts/products?limit=12' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+
+# Filter by category ID
+curl 'https://api.mystore.com/api/v3/store/products?q[categories_id_eq]=ctg_xxx' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+### By Tags
+
+
+```typescript SDK
+const { data: products } = await client.products.list({
+  tags_cont: 'sale',
+})
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/products?q[tags_cont]=sale' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+## Sorting
+
+
+```typescript SDK
+// Sort by price (low to high)
+const sorted = await client.products.list({
+  sort: 'price_low_to_high',
+})
+
+// Available sort options:
+// price_low_to_high, price_high_to_low, newest, name_a_z, name_z_a
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/products?sort=price_low_to_high' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+## Product Filters (Faceted Search)
+
+Get available filter options for building a faceted search UI. Returns option values, price ranges, and categories with counts:
+
+
+```typescript SDK
+const filters = await client.products.filters()
+// {
+//   option_types: [{ name: "size", option_values: [{ name: "Small", count: 12 }, ...] }],
+//   price_range: { min: 9.99, max: 199.99 },
+//   categories: [{ id: "ctg_xxx", name: "Clothing", count: 45 }],
+// }
+
+// Scoped to a specific category
+const categoryFilters = await client.products.filters({
+  category_id: 'ctg_xxx',
+})
+```
+
+```bash cURL
+# All filters
+curl 'https://api.mystore.com/api/v3/store/products/filters' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+
+# Scoped to a category
+curl 'https://api.mystore.com/api/v3/store/products/filters?category_id=ctg_xxx' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+## Filtering Other Resources
+
+The Store API uses query parameters prefixed with `q[]` for filtering any resource collection. Common filter predicates:
+
+### Equality Predicates
+
+| Predicate | Description | Example |
+|-----------|-------------|---------|
+| `eq` | Equals | `q[status_eq]=active` |
+| `not_eq` | Not equals | `q[status_not_eq]=archived` |
+| `in` | In array | `q[id_in][]=1&q[id_in][]=2` |
+
+### String Predicates
+
+| Predicate | Description | Example |
+|-----------|-------------|---------|
+| `cont` | Contains | `q[name_cont]=shirt` |
+| `start` | Starts with | `q[name_start]=spree` |
+| `end` | Ends with | `q[email_end]=@example.com` |
+| `i_cont` | Case-insensitive contains | `q[name_i_cont]=SHIRT` |
+
+### Comparison Predicates
+
+| Predicate | Description | Example |
+|-----------|-------------|---------|
+| `gt` | Greater than | `q[price_gt]=50` |
+| `gteq` | Greater than or equal | `q[quantity_gteq]=10` |
+| `lt` | Less than | `q[price_lt]=100` |
+| `lteq` | Less than or equal | `q[created_at_lteq]=2025-12-31` |
+
+### NULL Predicates
+
+| Predicate | Description | Example |
+|-----------|-------------|---------|
+| `null` | Is NULL | `q[deleted_at_null]=true` |
+| `not_null` | Is not NULL | `q[published_at_not_null]=true` |
+| `present` | Is not NULL and not empty | `q[image_present]=true` |
+
+> **INFO:** Only attributes explicitly allowed by each resource can be used for filtering. Attempting to filter on unsupported fields will be silently ignored.
+
+## Pagination
+
+All list endpoints support pagination:
+
+
+```typescript SDK
+const { data: products, meta } = await client.products.list({
+  page: 1,
+  limit: 24,
+})
+// meta.total_count => 150
+// meta.total_pages => 7
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/products?page=1&limit=24' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+See [Querying](/api-reference/store-api/querying) for the full list of filtering, sorting, and pagination options.
+
+## Search Providers
+
+Spree uses a pluggable search provider architecture. The default provider uses SQL (ILIKE + Ransack). For production catalogs with 1,000+ products, we recommend switching to [Meilisearch](/integrations/search/meilisearch) for typo tolerance, relevance ranking, and faster faceted search.
+
+```ruby
+# config/initializers/spree.rb
+Spree.search_provider = 'Spree::SearchProvider::Meilisearch'
+```
+
+No client-side or API changes are needed — the same `q[search]`, filter params, and sort options work with any provider.
+
+See [Build a Custom Search Provider](/developer/how-to/custom-search-provider) for architecture details and how to build custom providers.
+
+## Related Documentation
+
+- [Products](/developer/core-concepts/products) — Product catalog and listing
+- [Querying](/api-reference/store-api/querying) — API filtering, sorting, and pagination reference
+- [Build a Custom Search Provider](/developer/how-to/custom-search-provider) — Step-by-step guide
+- [Meilisearch Integration](/integrations/search/meilisearch) — Setup guide

package/dist/developer/core-concepts/shipments.md

@@ -0,0 +1,212 @@
+---
+title: Shipments
+description: Shipping methods, rates, split shipments, and fulfillment
+---
+
+## Overview
+
+A shipment represents a package being sent to a customer from a [Stock Location](/developer/core-concepts/inventory#stock-locations). Each order can have one or more shipments — Spree automatically splits orders into multiple shipments when items need to ship from different locations or require different shipping methods.
+
+```mermaid
+erDiagram
+    Order ||--o{ Shipment : "has many"
+    Shipment ||--o{ ShippingRate : "has many"
+    Shipment ||--o{ InventoryUnit : "has many"
+    Shipment }o--|| StockLocation : "ships from"
+    Shipment }o--|| ShippingMethod : "selected method"
+    ShippingMethod ||--o{ ShippingRate : "has many"
+    ShippingMethod }o--o{ Zone : "serves"
+    ShippingMethod }o--o{ ShippingCategory : "handles"
+    ShippingMethod }o--o{ Store : "available in"
+    Product }o--|| ShippingCategory : "belongs to"
+
+    Shipment {
+        string number
+        string tracking
+        string state
+        decimal cost
+        datetime shipped_at
+    }
+
+    ShippingMethod {
+        string name
+        string tracking_url
+        integer position
+    }
+
+    ShippingRate {
+        decimal cost
+        boolean selected
+    }
+```
+
+**Key relationships:**
+- **Shipment** tracks delivery of items from a [Stock Location](/developer/core-concepts/inventory#stock-locations)
+- **Shipping Method** defines the carrier/service (UPS, FedEx, etc.)
+- **Shipping Rate** represents the calculated cost for a method
+- **[Zone](/developer/core-concepts/addresses#zones)** defines geographic regions for shipping availability
+- **Shipping Category** groups products with similar shipping requirements
+
+## Shipment Attributes
+
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `number` | Unique shipment identifier | `H12345678901` |
+| `tracking` | Carrier tracking number | `1Z999AA10123456784` |
+| `state` | Current shipment state | `shipped` |
+| `cost` | Shipping cost | `9.99` |
+| `shipped_at` | When the shipment was shipped | `2025-07-21T14:36:00Z` |
+| `stock_location` | Where items ship from | `Warehouse NYC` |
+| `selected_shipping_rate` | The rate chosen by the customer | `{ cost: 9.99, name: "UPS Ground" }` |
+
+## Shipment States
+
+**Step 1: pending**
+
+The shipment has backordered inventory or the order is not yet paid.
+
+  **Step 2: ready**
+
+All items are in stock and the order is paid. Ready to ship.
+
+  **Step 3: shipped**
+
+The shipment is on its way to the customer.
+
+  **Step 4: canceled**
+
+The shipment was canceled. All items are restocked.
+
+
+## Selecting Shipping Rates
+
+During checkout, after the customer provides a shipping address, Spree calculates available shipping rates for each shipment. The customer must select a rate before proceeding.
+
+
+```typescript SDK
+// Get shipments with available shipping rates
+const order = await client.orders.get(orderId, {
+  expand: ['shipments'],
+})
+
+// Each shipment has available shipping rates
+order.shipments?.forEach(shipment => {
+  console.log(shipment.number)           // "H12345678901"
+  console.log(shipment.shipping_rates)   // [{ id: "sr_xxx", name: "UPS Ground", cost: "9.99", selected: true }, ...]
+})
+
+// Select a shipping rate
+await client.carts.shipments.update(cartId, shipment.id, {
+  selected_shipping_rate_id: 'sr_xxx',
+})
+```
+
+```bash cURL
+# Get shipments
+curl 'https://api.mystore.com/api/v3/store/carts/cart_xxx?expand=shipments' \
+  -H 'Authorization: Bearer spree_pk_xxx' \
+  -H 'X-Spree-Token: abc123'
+
+# Select a shipping rate
+curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/shipments/shp_xxx' \
+  -H 'Authorization: Bearer spree_pk_xxx' \
+  -H 'X-Spree-Token: abc123' \
+  -H 'Content-Type: application/json' \
+  -d '{ "selected_shipping_rate_id": "sr_xxx" }'
+```
+
+
+## Shipping Methods
+
+Shipping methods represent the carrier services available to customers (e.g., UPS Ground, FedEx Overnight, DHL International). Each shipping method is scoped to:
+
+- **[Zones](/developer/core-concepts/addresses#zones)** — geographic regions where the method is available
+- **Shipping Categories** — product groups the method handles
+- **[Stores](/developer/core-concepts/stores)** — which stores offer this method
+
+Only methods whose zone matches the customer's shipping address are offered at checkout.
+
+### Shipping Categories
+
+Shipping categories group products with similar shipping requirements. For example:
+
+- **Light** — lightweight items like stickers
+- **Regular** — standard products
+- **Heavy** — items over a certain weight
+- **Oversized** — large items requiring special handling
+
+Each product is assigned a shipping category. Shipping methods can be restricted to handle only certain categories, and the shipping cost calculator uses the category to determine pricing.
+
+### Calculators
+
+Each shipping method uses a [Calculator](/developer/core-concepts/calculators) to determine the cost. Spree includes these built-in calculators:
+
+| Calculator | Description |
+|------------|-------------|
+| Flat rate per order | Same cost regardless of items |
+| Flat rate per item | Fixed cost per item |
+| Flat percent | Percentage of the order total |
+| Flexible rate | One rate for the first item, another for each additional |
+| Price sack | Tiered pricing based on order total |
+
+You can create custom calculators for more complex pricing. See the [Calculators guide](/developer/core-concepts/calculators).
+
+## Split Shipments
+
+When items in an order ship from different stock locations or have different shipping categories, Spree automatically splits the order into multiple shipments.
+
+```mermaid
+flowchart TB
+    A[Order with 3 items] --> B{Stock check}
+    B --> C["Item A & B: NYC Warehouse"]
+    B --> D["Item C: LA Warehouse"]
+    C --> E["Shipment 1: UPS Ground"]
+    D --> F["Shipment 2: FedEx 2Day"]
+```
+
+### How Splitting Works
+
+1. When an order reaches the delivery step, Spree evaluates where each item is in stock
+2. Items are grouped by stock location and shipping category
+3. Each group becomes a separate shipment with its own shipping rates
+4. The customer selects a shipping rate for each shipment independently
+
+### Weight Splitting
+
+By default, Spree also splits shipments when a package exceeds a weight threshold (default: 150 units). This prevents individual packages from being too heavy.
+
+> **INFO:** Split shipment behavior is customizable. See the [Customization Quickstart](/developer/customization/quickstart) for details on creating custom splitting rules.
+
+## Examples
+
+### Simple Setup
+
+A store selling T-shirts to the US and Europe with 2 carriers:
+
+| Method | Zone | Pricing |
+|--------|------|---------|
+| USPS Ground | US | $5 first item + $2 each additional |
+| FedEx | EU | $10 per item |
+
+This requires:
+- 1 shipping category (default)
+- 1 stock location
+- 2 shipping methods with appropriate zones and calculators
+
+### Advanced Setup
+
+A store shipping from 2 locations (New York, Los Angeles) with 3 carriers and 3 shipping categories:
+
+| Category / Method | DHL | FedEx | USPS |
+|:-|:-|:-|:-|
+| Light | $5/item | $10 flat | $8/item |
+| Regular | $5/item | $2/item | $8/item |
+| Heavy | $50/item | $20 + $15/add'l | $20/item |
+
+## Related Documentation
+
+- [Orders](/developer/core-concepts/orders) — Checkout flow and shipping rate selection
+- [Inventory](/developer/core-concepts/inventory) — Stock locations and inventory management
+- [Calculators](/developer/core-concepts/calculators) — Shipping rate calculators
+- [Addresses](/developer/core-concepts/addresses) — Shipping address and zones
+- [Events](/developer/core-concepts/events) — Subscribe to shipment events (e.g., `shipment.shipped`)

package/dist/developer/core-concepts/slugs.md

@@ -0,0 +1,111 @@
+---
+title: Slugs
+description: SEO-friendly URL identifiers for products, categories, and other resources
+---
+
+## Overview
+
+Spree generates SEO-friendly URL slugs for resources like products, categories, and stores. Instead of accessing resources by ID, you can use clean, readable URLs based on resource names.
+
+Both the Store API and Admin API accept slugs or IDs interchangeably for resource lookups.
+
+
+```typescript SDK
+// Both work — slug or ID
+const product = await client.products.get('spree-tote')
+const product = await client.products.get('prod_86Rf07xd4z')
+
+// Categories use permalink slugs
+const category = await client.categories.get('clothing/shirts')
+```
+
+```bash cURL
+# By slug
+curl 'https://api.mystore.com/api/v3/store/products/spree-tote' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+
+# By ID
+curl 'https://api.mystore.com/api/v3/store/products/prod_86Rf07xd4z' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+
+## Slug Generation
+
+Slugs are automatically generated from resource names:
+
+| Input | Generated Slug |
+|-------|---------------|
+| `Spree T-Shirt` | `spree-t-shirt` |
+| `Café & Restaurant` | `cafe-and-restaurant` |
+| `Summer Collection 2025` | `summer-collection-2025` |
+
+If a slug already exists, Spree appends the SKU or a unique identifier to ensure uniqueness.
+
+## Models with Slugs
+
+| Resource | Slug Column | Translatable | Hierarchical |
+|----------|-------------|:---:|:---:|
+| Product | `slug` | Yes | No |
+| Category | `permalink` | Yes | Yes |
+| Store | `code` | No | No |
+| Post | `slug` | Yes | No |
+
+### Category Permalinks
+
+Category slugs include the full parent path, making them hierarchical:
+
+```
+clothing                       → "clothing"
+clothing/shirts                → "clothing/shirts"
+clothing/shirts/t-shirts       → "clothing/shirts/t-shirts"
+```
+
+When a parent category is renamed, all child permalinks update automatically.
+
+## Slug History
+
+When a slug changes (e.g., a product is renamed), Spree preserves the old slug. Requests using old slugs still find the resource, enabling:
+
+- **SEO continuity** — no broken links when names change
+- **Bookmark compatibility** — saved URLs keep working
+- **Graceful URL migration** — old links resolve automatically
+
+## Internationalization
+
+Products, categories, and posts support localized slugs — a different slug per locale:
+
+
+```typescript SDK
+// English
+const product = await client.products.get('red-shoes')
+
+// French (with locale header)
+const product = await client.products.get('chaussures-rouges', {
+  locale: 'fr',
+})
+```
+
+```bash cURL
+# English
+curl 'https://api.mystore.com/api/v3/store/products/red-shoes' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+
+# French
+curl 'https://api.mystore.com/api/v3/store/products/chaussures-rouges' \
+  -H 'Authorization: Bearer spree_pk_xxx' \
+  -H 'X-Spree-Locale: fr'
+```
+
+
+Slugs are unique within the same locale but can be duplicated across different locales.
+
+## Reserved Words
+
+Spree prevents certain words from being used as slugs to avoid route conflicts: `new`, `edit`, `index`, `login`, `logout`, `admin`, and others.
+
+## Related Documentation
+
+- [Products](/developer/core-concepts/products) — Product catalog
+- [Translations](/developer/core-concepts/translations) — Multi-language content
+- [Querying](/api-reference/store-api/querying) — API resource lookup

package/dist/developer/core-concepts/staff-roles.md

@@ -0,0 +1,123 @@
+---
+title: Staff & Roles
+description: Admin users, roles, invitations, and permissions
+---
+
+## Overview
+
+Admin users manage the store via the Admin Panel. They have roles that control what they can access.
+
+```mermaid
+erDiagram
+    AdminUser ||--o{ RoleUser : "has many"
+    RoleUser }o--|| Role : "belongs to"
+    RoleUser }o--|| Store : "scoped to"
+    AdminUser ||--o{ Invitation : "invites"
+
+    AdminUser {
+        string id
+        string email
+    }
+
+    RoleUser {
+        string role_id
+        string resource_type
+        string resource_id
+    }
+
+    Role {
+        string name
+    }
+
+    Invitation {
+        string email
+        string status
+        string token
+        datetime expires_at
+    }
+```
+
+## Roles
+
+Admin users can have different roles that control their permissions:
+
+| Role | Description |
+|------|-------------|
+| `admin` | Full access to all Admin Panel features |
+
+> **INFO:** You can create custom roles with specific permissions. See the [Customize Permissions guide](/developer/customization/permissions) for details.
+
+## Creating Admin Users
+
+Use the Spree CLI to create admin users:
+
+```bash
+spree user create
+```
+
+The CLI will prompt you for the email and password. You can also pass them directly:
+
+```bash
+spree user create --email admin@example.com --password secret123
+```
+
+The created user gets the `admin` role on the default store.
+
+## Inviting Admin Users
+
+You can invite new admins through the Admin Panel or programmatically.
+
+**Via Admin Panel:**
+
+1. Navigate to **Settings → Users**
+2. Click **Invite User**
+3. Enter the email address and select a role
+4. Click **Send Invitation**
+
+The invitee receives an email with an invitation link. If they already have an account, they log in to accept. Otherwise, they create an account first.
+
+```mermaid
+flowchart TB
+    A[Admin creates invitation] --> B[Invitation email sent]
+    B --> C[Invitee clicks link]
+    C --> D{Has account?}
+    D -->|Yes| E[Log in]
+    D -->|No| F[Create account]
+    E --> G[Accept invitation]
+    F --> G
+    G --> H[Role assigned to store]
+```
+
+### Invitation Details
+
+| Attribute | Description |
+|-----------|-------------|
+| `email` | Invitee's email address |
+| `token` | Secure token for the invitation link |
+| `status` | `pending` or `accepted` |
+| `expires_at` | Expiration date (default: 2 weeks) |
+| `resource` | The store being granted access to |
+| `role` | The role to assign upon acceptance |
+
+### Invitation Events
+
+The invitation system publishes [events](/developer/core-concepts/events) you can subscribe to:
+
+| Event | Description |
+|-------|-------------|
+| `invitation.created` | Invitation was created (triggers email) |
+| `invitation.accepted` | Invitation was accepted and role assigned |
+| `invitation.resent` | Invitation was resent to the invitee |
+
+## Permissions
+
+Spree uses [CanCanCan](https://github.com/CanCanCommunity/cancancan) for authorization. Permissions apply to both customers (Store API access) and admins (Admin Panel access).
+
+See the [Customize Permissions guide](/developer/customization/permissions) for details on creating custom roles and permission sets.
+
+## Related Documentation
+
+- [Customers](/developer/core-concepts/customers) — Customer accounts and authentication
+- [Stores](/developer/core-concepts/stores) — Multi-store setup
+- [Permissions](/developer/customization/permissions) — Roles and authorization
+- [Events](/developer/core-concepts/events) — Subscribe to invitation events