@spree/docs 0.1.177 → 0.1.178

package/dist/developer/tutorial/dashboard-plugin.md

@@ -0,0 +1,14 @@
+---
+title: Dashboard Plugin
+description: Scaffold a dashboard plugin for ProductFaqs — a table, a form, and navigation, generated by the CLI and wired to the Admin API endpoint.
+---
+
+With the Admin API in place, the back-office UI is a dashboard plugin: a table listing FAQs, a form to create and edit them, and a navigation entry — scaffolded by the CLI and customized from there.
+
+## What this chapter covers
+
+- Scaffolding the plugin with the CLI
+- The resource table: columns, search and pagination against the Admin API
+- The form: fields, validation errors mapped from API responses
+- Registering navigation and permissions-aware visibility
+- Running it against your development store

package/dist/developer/tutorial/events.md

@@ -1,166 +1,12 @@
 ---
-title: Events & Webhooks
-description: React to Spree store activity and connect to external systems like an OMS, warehouse, or ERP using event subscribers, the subscriber generator, and webhooks.
+title: Events
+description: Publish lifecycle events for FAQs and react to them — subscribers inside the app, webhooks for systems outside it.
 ---
 
-> **INFO:** This guide assumes you've completed the [Model](model.md) and [API](api.md) tutorials — we'll reuse the Brand serializer created there.
+Features rarely live alone — something usually needs to know when data changes. This chapter publishes lifecycle events for FAQs and consumes them both ways.
 
-Almost every real store talks to other systems: an order management system (OMS), a warehouse (WMS), an ERP, a CRM, a marketing platform. In Spree, the integration surface is the **events system** — models publish events as things happen, and you react to them without touching core code.
+## What this chapter covers
 
-There are two ways to consume events, and they serve different audiences:
-
-| Mechanism | Code lives | Best for |
-|---|---|---|
-| **Subscriber** | In your Spree app | Calling external APIs with your own client code, internal side effects, anything needing app context |
-| **Webhook** | In the external system | Letting a third party receive HTTP callbacks — no Ruby in your app, endpoints managed from the admin |
-
-We'll do both: push completed orders to an OMS with a subscriber, give the Brand model its own lifecycle events, and set up an outbound webhook.
-
-## Step 1: Subscribe to a Core Event
-
-When an order completes, send it to the OMS. Generate a subscriber:
-
-
-```bash Spree CLI (Docker)
-spree generate subscriber OmsOrderSync order.completed
-```
-
-```bash Without Spree CLI
-bin/rails g spree:subscriber OmsOrderSync order.completed
-```
-
-
-This creates the subscriber, a spec stub, and — crucially — **registers it** in `config/initializers/spree.rb` (injected into the existing `after_initialize` block every Spree app ships with). Subscribers are not auto-discovered; a subscriber that never gets appended to `Spree.subscribers` is a silent no-op, which is why the generator owns that step (re-runs are idempotent, and each new subscriber appends to the same initializer).
-
-Fill in the handler:
-
-```ruby app/subscribers/oms_order_sync_subscriber.rb
-class OmsOrderSyncSubscriber < Spree::Subscriber
-  subscribes_to 'order.completed'
-
-  def handle(event)
-    order = Spree::Order.find_by_prefix_id(event.payload['id'])
-    return unless order
-
-    OmsClient.create_order(
-      number: order.number,
-      email: order.email,
-      line_items: order.line_items.map { |li| { sku: li.sku, quantity: li.quantity } }
-    )
-  end
-end
-```
-
-Two things worth understanding:
-
-- **Payloads carry prefixed IDs**, not raw database IDs — always look records up with `find_by_prefix_id`. The payload itself is the resource serialized with its v3 API serializer, so `event.payload['number']`, `['email']`, etc. are available directly when you don't need the full record.
-- **Subscribers run async by default** — each `handle` call is an ActiveJob on the events queue, so a slow OMS API never blocks checkout. Pass `subscribes_to 'order.completed', async: false` only when you genuinely need synchronous execution.
-
-Restart the server, complete a test order, and watch the job fire (`spree logs worker` — or your job backend's UI).
-
-## Step 2: Give Brand Its Own Lifecycle Events
-
-Core models like Payment and Shipment publish `*.created` / `*.updated` / `*.deleted` events automatically. Your models can too — add one line to the Brand model:
-
-```ruby app/models/spree/brand.rb {3}
-module Spree
-  class Brand < Spree.base_class
-    publishes_lifecycle_events
-
-    # ... existing code ...
-  end
-end
-```
-
-Now `brand.created`, `brand.updated`, and `brand.deleted` fire after the matching transactions commit — and because you created `Spree::Api::V3::BrandSerializer` in the [API step](api.md), the payloads automatically use it (the events system resolves the serializer by naming convention). Anyone — subscriber or webhook — can react to brand changes with the same JSON shape your API serves.
-
-
-```bash Spree CLI (Docker)
-spree generate subscriber BrandSync brand.created brand.updated
-```
-
-```bash Without Spree CLI
-bin/rails g spree:subscriber BrandSync brand.created brand.updated
-```
-
-
-```ruby app/subscribers/brand_sync_subscriber.rb
-class BrandSyncSubscriber < Spree::Subscriber
-  subscribes_to 'brand.created', 'brand.updated'
-
-  def handle(event)
-    SearchIndexer.upsert_brand(event.payload)
-  end
-end
-```
-
-## Step 3: Publish a Custom Event
-
-Lifecycle events cover persistence; custom events express *domain* moments. Say featuring a brand should notify the marketing platform:
-
-```ruby
-brand.publish_event('brand.featured')
-```
-
-The payload defaults to the serializer output; pass your own hash as the second argument when the event needs different data. Subscribers consume it like any other event name.
-
-## Step 4: Outbound Webhooks — No Code Required
-
-When the consumer is an external system you don't deploy code into, use webhooks. In the admin, go to **Settings → Webhooks**, add an endpoint with the destination URL, and pick the events to deliver — `order.completed`, `brand.created`, anything publishing in your store. The endpoint's **signing secret is shown once on creation** — store it in the receiving system.
-
-Each delivery is an HTTP POST with this envelope:
-
-```json
-{
-  "id": "550e8400-e29b-41d4-a716-446655440000",
-  "name": "order.completed",
-  "created_at": "2026-06-11T12:00:00Z",
-  "data": { "id": "or_m3Rp9wXz", "number": "R123456789", "...": "..." },
-  "metadata": {}
-}
-```
-
-And three headers the receiver should use:
-
-| Header | Contents |
-|---|---|
-| `X-Spree-Webhook-Event` | The event name |
-| `X-Spree-Webhook-Timestamp` | Unix timestamp of the delivery |
-| `X-Spree-Webhook-Signature` | `HMAC-SHA256(secret, "{timestamp}.{body}")` |
-
-Verify the signature before trusting a payload:
-
-```ruby
-def verified?(request, secret)
-  timestamp = request.headers['X-Spree-Webhook-Timestamp']
-  expected  = OpenSSL::HMAC.hexdigest('SHA256', secret, "#{timestamp}.#{request.raw_post}")
-  ActiveSupport::SecurityUtils.secure_compare(expected, request.headers['X-Spree-Webhook-Signature'])
-end
-```
-
-Delivery semantics to design around: failed deliveries (timeouts, connection errors, non-2xx responses) are **recorded, not retried automatically** — redeliver from the endpoint's delivery history in the admin, or via `POST /api/v3/admin/webhook_endpoints/:webhook_endpoint_id/deliveries/:id/redeliver`. After **15 consecutive failures** the endpoint auto-disables and store staff get an email; a successful delivery resets the counter.
-
-## Testing a Subscriber
-
-Subscribers are plain Ruby — test `handle` directly with a constructed event:
-
-```ruby spec/subscribers/oms_order_sync_subscriber_spec.rb
-require 'rails_helper'
-
-RSpec.describe OmsOrderSyncSubscriber do
-  it 'pushes completed orders to the OMS' do
-    order = create(:completed_order_with_totals)
-    event = Spree::Event.new(name: 'order.completed', payload: { 'id' => order.prefixed_id })
-
-    expect(OmsClient).to receive(:create_order).with(hash_including(number: order.number))
-
-    described_class.new.handle(event)
-  end
-end
-```
-
-## Related Documentation
-
-- [Events](../core-concepts/events.md) — the full event catalog, subscriber DSL, and delivery guarantees
-- [Webhooks](../core-concepts/webhooks.md) — endpoint management, security, and the per-event payload schemas
-- [Extending Core Models](extending-models.md) — when a decorator is the right tool instead
+- Publishing lifecycle events from the model
+- A subscriber reacting inside the application
+- Delivering the event to an external system as a webhook

package/dist/developer/tutorial/introduction.md

@@ -1,44 +1,24 @@
 ---
-title: Tutorial
-sidebarTitle: Introduction
-description: Build a complete custom Brands feature in Spree — model, admin UI, Store and Admin APIs, events, and TypeScript storefront integration — end to end.
+title: "Tutorial: Build a Custom Feature"
+description: Build Product FAQs end to end — a custom model, an Admin API endpoint, a dashboard plugin, a Store API endpoint, and storefront rendering through the TypeScript SDK.
 ---
 
-This tutorial walks you through creating a complete Spree feature from scratch: a "Brands" feature that lets admins manage [Product](../core-concepts/products.md) brands, exposes them through the Store API, and consumes them from TypeScript.
+This tutorial builds one complete feature — **Product FAQs**, questions and answers attached to products — through every layer of a Spree 6 application. By the end you will have a custom model, back-office management in the dashboard, and customer-facing display on the storefront.
 
-It's written for **both backend and frontend developers**. The Ruby you'll write is minimal and mostly generated — Spree's generators produce convention-correct models, admin UIs, and API endpoints, and the TypeScript SDK gives you typed access from your storefront. You don't need to be a Rails expert to follow along.
+## The two tracks
 
-## Before you start
-
-You need a running Spree app. The fastest path is [create-spree-app](../create-spree-app/quickstart.md) — a Docker-based project with the [Spree CLI](../cli/quickstart.md), no local Ruby required:
-
-```bash
-npx create-spree-app@latest my-store
-```
-
-An existing app with Spree gems works just as well. **Every command in this tutorial is shown in two forms** — **Spree CLI** (runs inside Docker) and **Without Spree CLI** (runs directly on your machine) — pick the tab that matches your setup and ignore the other.
+The tutorial is organized so you only build what your feature needs:
 
-> **NOTE:** **create-spree-app projects:** run `spree eject` once before starting. Fresh projects use a prebuilt Docker image; ejecting switches to the dev setup that mounts `backend/` into the container, so the files the generators create land in your project (and reload live as you edit them).
+| Track | Chapters | Build this when |
+|---|---|---|
+| Foundation | [Model](model.md) | Always |
+| **A — manage it in the dashboard** | [Admin API](admin-api.md) → [Dashboard plugin](dashboard-plugin.md) | The feature is operated by staff — internal tooling, back-office data |
+| **B — expose it on the storefront** | [Store API](store-api.md) → [Storefront](storefront.md) | Customers see the feature |
+| Finishing | [Events](events.md) → [Testing](testing.md) | Always |
 
-> **TIP:** Using an AI coding agent? Install the [Spree agent skills](../agentic/agent-skills.md) (`npx skills add spree/agent-skills`) and connect the [docs MCP server](../agentic/mcp.md) before starting — your agent will know the conventions this tutorial teaches and can follow along with you. See [Agentic Development](../agentic/overview.md).
-
-## What you'll build
-
-* A `Brand` model with a rich text description and an uploadable logo — one generator command
-* An admin UI for managing brands — one generator command, then customized
-* A `brand` association on Products, surfaced in the product admin form
-* Store API endpoints (`GET /api/v3/store/brands`) with serializers and prefixed IDs
-* Typed TypeScript access to brands from your storefront via `@spree/sdk`
-* Event subscribers and webhooks connecting the store to external systems
-* Automated tests for all of it
-
-## Tutorial Sections
+An internal tool is Track A alone. A storefront feature over existing data is Track B alone. Product FAQs need both: staff write the answers, customers read them.
 
+## Before you start
 
-  - [1. Model](model.md) — Generate the Brand model — columns, rich text description, and logo upload in one command
-  - [2. Admin Dashboard](admin.md) — Scaffold the admin UI, then add the description editor, logo upload, and table columns
-  - [3. Extending Core Models](extending-models.md) — Connect Brands to Products using a decorator and an association
-  - [4. API](api.md) — Expose Brands through the Store and Admin APIs — generated in one command, or hand-built to learn the pieces
-  - [5. Events & Webhooks](events.md) — React to store activity and connect external systems — OMS, warehouse, ERP
-  - [6. SDK](sdk.md) — Consume Brand endpoints from TypeScript using the SDK
-  - [7. Testing](testing.md) — Write automated tests for your feature
+- A running Spree application — see the [quickstart](../getting-started/quickstart.md)
+- The AI tooling set up — the [agent skills and MCP server](../agentic/overview.md) make every step of this tutorial faster

package/dist/developer/tutorial/model.md

@@ -1,104 +1,13 @@
 ---
 title: Model
-description: Create a custom Brand model in Spree with database columns, a rich text description, and an Active Storage logo upload using a single generator command.
+description: Generate the ProductFaq model — migration, associations, validations and store scoping — the foundation both tracks build on.
 ---
 
-> **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.
+Every feature starts with a model. This chapter generates `ProductFaq` — question, answer, position, attached to a product and scoped to the store.
 
-In this step we'll create the `Spree::Brand` model with everything it needs: a `name` column, a rich text `description`, and an uploadable `logo`.
+## What this chapter covers
 
-## Step 1: Generate the Model
-
-Spree ships a `spree:model` generator that produces a model and migration following all Spree conventions — `Spree::` namespacing, prefixed IDs, presence validations, and API filtering allowlists. It understands Rails attribute types including the virtual ones, so rich text and file attachments are part of the same command:
-
-
-```bash Spree CLI (Docker)
-spree generate model Brand name:string:index description:rich_text logo:attachment
-```
-
-```bash Without Spree CLI
-bin/rails g spree:model Brand name:string:index description:rich_text logo:attachment
-```
-
-
-> **INFO:** Throughout this tutorial every command is shown in two forms. **Spree CLI** is for projects created with [create-spree-app](../create-spree-app/quickstart.md), where the app runs in Docker and `spree <command>` routes into the container. **Without Spree CLI** is for apps running Spree backend directly on your machine.
-
-This creates two files:
-
-- `app/models/spree/brand.rb` — the model
-- `db/migrate/XXXXXXXXXXXXXX_create_spree_brands.rb` — the migration
-
-Now apply the migration:
-
-
-```bash Spree CLI (Docker)
-spree migrate
-```
-
-```bash Without Spree CLI
-bin/rails db:migrate
-```
-
-
-This creates the `spree_brands` table with an indexed `name` column. The `description` and `logo` attributes don't add columns — rich text lives in Action Text's `action_text_rich_texts` table, and uploads live in Active Storage's tables.
-
-## Step 2: Understand the Generated Model
-
-Open `app/models/spree/brand.rb`:
-
-```ruby app/models/spree/brand.rb
-module Spree
-  class Brand < Spree.base_class
-    has_prefix_id :brand
-
-    has_rich_text :description
-    has_one_attached :logo
-
-    validates :name, presence: true
-
-    self.whitelisted_ransackable_attributes = %w[name]
-    self.whitelisted_ransackable_associations = %w[]
-    self.whitelisted_ransackable_scopes = %w[]
-  end
-end
-```
-
-Line by line:
-
-- **`Spree.base_class`** — inherits all Spree model functionality (multi-store scoping helpers, preferences, and more). The class is namespaced under `Spree::`, so it's available as `Spree::Brand`.
-- **`has_prefix_id :brand`** — records get Stripe-style public IDs like `brand_k5nR8xLq`. APIs never expose raw database IDs.
-- **`has_rich_text :description`** — formatted content via [Action Text](https://guides.rubyonrails.org/action_text_overview.html).
-- **`has_one_attached :logo`** — file uploads via [Active Storage](https://guides.rubyonrails.org/active_storage_overview.html), with image processing and direct-to-storage uploads.
-- **`validates :name, presence: true`** — generated automatically for required columns.
-- **`whitelisted_ransackable_attributes`** — controls which attributes API clients may filter and sort by. Only allowlisted attributes are queryable, so adding `name` here is what later makes `?q[name_cont]=nike` work.
-
-## Step 3: Try It in the Console
-
-
-```bash Spree CLI (Docker)
-spree console
-```
-
-```bash Without Spree CLI
-bin/rails console
-```
-
-
-```ruby
-brand = Spree::Brand.create!(name: "Wilson")
-brand.prefixed_id           # => "brand_k5nR8xLq"
-
-brand.update!(description: "<h1>Hello</h1><p>World</p>")
-brand.description.to_s             # => rendered rich text HTML
-brand.description.to_plain_text    # => "Hello World"
-
-Spree::Brand.find_by_prefix_id!("brand_k5nR8xLq")  # lookup by public ID
-```
-
-We'll upload the logo through the admin UI in the next step — the model side is already done.
-
-> **TIP:** The generator accepts more attribute types and options — references with auto-resolved class names (`user:belongs_to`), unique indexes (`slug:string:uniq`), soft delete (`--paranoid`), and custom fields support (`--metafields`). Run it with `--help` to see everything.
-
-## Next Step
-
-The model is complete. Now let's give admins a UI to manage brands: [Admin Dashboard](admin.md).
+- Generating the model and migration from the command line
+- Store scoping — why every store-owned record belongs to a store, and what that buys you
+- The association to products, validations, and ordering
+- Running the migration and creating a record in the console

package/dist/developer/tutorial/store-api.md

@@ -0,0 +1,13 @@
+---
+title: Store API
+description: Expose FAQs to customers — a read-only Store API endpoint with a serializer that shows only what shoppers should see.
+---
+
+Customers read FAQs through the Store API. This chapter adds the customer-facing endpoint — read-only, scoped to the current store, with a serializer deliberately smaller than the admin one.
+
+## What this chapter covers
+
+- The store resource controller: read-only by default, and why
+- The store serializer: public fields only — no timestamps, no internal data
+- Scoping: only FAQs for purchasable products of the current store
+- Nesting under the product endpoint

package/dist/developer/tutorial/storefront.md

@@ -0,0 +1,12 @@
+---
+title: Storefront
+description: Render FAQs on the product page — regenerate the SDK types, extend the TypeScript client, and build the component in the Next.js storefront.
+---
+
+The Store API endpoint becomes typed TypeScript and a component on the product page. This chapter closes the loop from Rails model to customer screen.
+
+## What this chapter covers
+
+- The type generation pipeline: serializer to TypeScript types to runtime schemas
+- Extending the SDK client with the new resource
+- Fetching and rendering FAQs on the product detail page in the Next.js storefront