Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Fixed Price Serializer and clean up CLAUDE.md file
Damian Legawiec1cf876d6eb4e
diff --git a/CLAUDE.md b/CLAUDE.mdindex c5ac879ba2..9936e275c8 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -94,7 +94,7 @@ For uniqueness validation, always use `scope: spree_base_uniqueness_scope`### Controller Inheritance- Admin controllers inherit from `Spree::Admin::ResourceController` which handles most of CRUD operations-- API v3 controllers inherit from `Spree::Api::V3::BaseController`+- Store API controllers inherit from `Spree::Api::V3::Store::ResourceController`- Storefront controllers inherit from `Spree::StoreController`### Parameter Handling@@ -109,6 +109,98 @@ def permitted_product_paramsend```+## API Development++### Serializers++API v3 uses Alba serializers located in `api/app/serializers/spree/api/v3/`. We have separate serializers for Store and Admin APIs:++- **Store serializers** (`app/serializers/spree/api/v3/`) - Customer-facing, limited data+- **Admin serializers** (`app/serializers/spree/api/v3/admin/`) - Full access, extends store serializers++Admin serializers inherit from store serializers and add additional fields.++```ruby+# Store serializer - customer-facing+module Spree::Api::V3+ class ProductSerializer < BaseSerializer+ typelize purchasable: :boolean, in_stock: :boolean, price: 'number | null'++ attributes :id, :name, :description, :slug, :price+ end+end++# Admin serializer - extends store with admin-only fields+module Spree::Api::V3::Admin+ class ProductSerializer < V3::ProductSerializer+ typelize cost_price: 'number | null', private_metadata: 'Record<string, unknown> | null'++ attributes :status, :cost_price, :private_metadata+ end+end+```++Never use `typelize_from` in serializers this causes serializers to connnect to the database.++### TypeScript Type Generation++We use [typelizer](https://github.com/skryukov/typelizer) to generate TypeScript types from Alba serializers:++- Types are generated to `sdk/src/types/generated/`+- Store types: `StoreProduct`, `StoreOrder`, etc.+- Admin types: `AdminProduct`, `AdminOrder`, etc.+- Run `bundle exec rake typelizer:generate` to regenerate types++### Serializer DSL++- `typelize attr: :type` - Define types for computed/delegated attributes+- Use `Spree.api.serializer_name` for configurable serializer references++### API Authentication++API uses Publishable and Secret API Keys for authentication. Publishable works for Store API and Secret for Admin API.++## Events System++When adding new functionality that other parts of the system (or external integrations) might need to react to, fire events using Spree's event system:++```ruby+order.publish_event('order.completed')+```++Place subscriber classes in `app/subscribers/spree/` directory:++```ruby+# app/subscribers/spree/order_webhook_subscriber.rb+module Spree+ module OrderWebhookSubscriber+ include Spree::Event::Subscriber++ event_action :order_completed++ def order_completed(event)+ order = event.payload[:order]+ # Handle the event+ end+ end+end+```++For new models that publish events, please add `publishes_lifecycle_events` concern to the model.++You also need to create an event serializer for the model, see [Events](/docs/developer/core-concepts/events.mdx) for more details.++## Dependencies System++When building services that users might want to swap out, register them in `Spree::Dependencies`:++```ruby+# In the dependency configuration+Spree::Dependencies.cart_add_item_service = 'Spree::Cart::AddItem'+```++This allows users to replace services without modifying core code.+## Admin DevelopmentWhen adding new resources to the admin, you need to register tables and navigation.@@ -222,99 +314,6 @@ Navigation options:- `badge` - Lambda returning badge text- `badge_class` - CSS class for badge-## API v3 Development--### Serializers--API v3 uses Alba serializers located in `api/app/serializers/spree/api/v3/`. Following Medusa's pattern, we have separate serializers for Store and Admin APIs:--- **Store serializers** (`app/serializers/spree/api/v3/`) - Customer-facing, limited data-- **Admin serializers** (`app/serializers/spree/api/v3/admin/`) - Full access, extends store serializers--```ruby-# Store serializer - customer-facing-module Spree::Api::V3- class ProductSerializer < BaseSerializer- typelize_from Spree::Product- typelize purchasable: :boolean, in_stock: :boolean, price: 'number | null'-- attributes :id, :name, :description, :slug, :price- end-end--# Admin serializer - extends store with admin-only fields-module Spree::Api::V3::Admin- class ProductSerializer < V3::ProductSerializer- typelize_from Spree::Product- typelize cost_price: 'number | null', private_metadata: 'Record<string, unknown> | null'-- attributes :status, :cost_price, :private_metadata- end-end-```--### TypeScript Type Generation--We use [typelizer](https://github.com/skryukov/typelizer) to generate TypeScript types from Alba serializers:--- Types are generated to `sdk/src/types/generated/`-- Store types: `StoreProduct`, `StoreOrder`, etc.-- Admin types: `AdminProduct`, `AdminOrder`, etc.-- Run `bundle exec rake typelizer:generate` to regenerate types--### Serializer DSL--- `typelize_from Model` - Connect serializer to ActiveRecord model for type inference-- `typelize attr: :type` - Define types for computed/delegated attributes-- Use `Spree.api.serializer_name` for configurable serializer references--### API Authentication--API v3 uses API keys with scopes:-- `store` scope - Customer-facing operations (cart, checkout, account)-- `admin` scope - Administrative operations (full CRUD access)--## Events System--When adding new functionality that other parts of the system (or external integrations) might need to react to, fire events using Spree's event system:--```ruby-order.publish_event('order.completed')-```--Place subscriber classes in `app/subscribers/spree/` directory:--```ruby-# app/subscribers/spree/order_webhook_subscriber.rb-module Spree- module OrderWebhookSubscriber- include Spree::Event::Subscriber-- event_action :order_completed-- def order_completed(event)- order = event.payload[:order]- # Handle the event- end- end-end-```--For new models that publish events, please add `publishes_lifecycle_events` concern to the model.--You also need to create an event serializer for the model, see [Events](/docs/developer/core-concepts/events.mdx) for more details.--## Dependencies System--When building services that users might want to swap out, register them in `Spree::Dependencies`:--```ruby-# In the dependency configuration-Spree::Dependencies.cart_add_item_service = 'Spree::Cart::AddItem'-```--This allows users to replace services without modifying core code.-## Testing### Test Application@@ -325,10 +324,11 @@ This will create a dummy rails application and run migrations. If there's alread### Test Structure-- Use RSpec for testing+- Use RSpec for testing and Factory Bot for creating test data+- As much as you can use build vs create for Factories to speed up tests+- Be very pragmatic, and don't over-engineer tests, don't repeat same tests in multiple places, tests must be fast- Create test app with `bundle exec rake test_app` in every gem directory (eg. admin, api, core, etc.)- Place specs in appropriate directories matching app structure-- Use Spree's factory bot definitions- For controller specs always add `render_views` to the test- For controller spec authentication use `stub_authorization!`- Don't create test scenarios for standard rails validation, only for custom validations@@ -425,21 +425,14 @@ end## Frontend Development-### Storefront Development--- Use Tailwind CSS for styling-- Follow responsive design principles-- Implement proper SEO meta tags-- Ensure accessibility compliance-### Admin Interface- Use Spree's admin styling conventions- Use as much as possible Turbo Rails features (Hotwire)-- Re-usable components should be helpers-- Please use `Spree::Admin::FormBuilder` methods for form fields-- Follow UX patterns established in core admin- Use Stimulus controllers for JavaScript interactions+- Please use [Admin Components](docs/developer/admin/components.mdx) for elements such as dialogs, drawers, dropdowns, and more.+- Please use [Spree::Admin::FormBuilder](docs/developer/admin/form-builder.mdx) methods for form fields+- For rendering record lists please use [Admin Tables](docs/developer/admin/tables.mdx)For create new resource form:@@ -476,23 +469,23 @@ And the re-usable form partial should be in `app/views/spree/admin/products/_for### Query Optimization-- Use includes/preload to avoid N+1 queries+- We're using ar_lazy_preload gem to avoid N+1 queries, however please use includes/preload to avoid N+1 queries as much as possible- Implement proper database indexing- Use scopes for reusable query logic- Consider caching for expensive operations```ruby# ✅ Optimized queries-products = Spree::Product.includes(:variants, :images)+products = Spree::Product.includes(:variants, :thumbnail).where(available_on: ..Time.current).order(:name)```### Caching-- Use Rails caching mechanisms appropriately-- Cache expensive calculations and queries-- Implement cache invalidation strategies+- Use Rails caching mechanisms appropriately (via `Rails.cache`)+- Cache expensive calculations and queries, however caching one query is not recommended+- Implement cache invalidation strategies, use Rails `cache_key_with_version` when constructing custom cache keys- Consider fragment caching for views### Code Quality@@ -502,6 +495,9 @@ products = Spree::Product.includes(:variants, :images)- Use meaningful variable and method names- Write self-documenting code with appropriate comments- Avoid deep nesting and complex conditionals+- Avoid business logic in controllers, move that to models and use concerns+- Use services only when necessary, we should as much as we possible use standard Rails models and Concerns+- Use concerns for reusable code## Documentation & Commentsdiff --git a/api/CLAUDE.md b/api/CLAUDE.mddeleted file mode 100644index 10662cb38a..0000000000--- a/api/CLAUDE.md+++ /dev/null@@ -1,235 +0,0 @@-# Claude Code Rules for Spree API Development--## API v3 Architecture--### Serializers--API v3 uses Alba serializers following Medusa's pattern with separate Store and Admin types:--**Directory Structure:**-- `app/serializers/spree/api/v3/` - Store serializers (customer-facing)-- `app/serializers/spree/api/v3/admin/` - Admin serializers (extends store serializers)--**Creating a Store Serializer:**--```ruby-module Spree- module Api- module V3- class ProductSerializer < BaseSerializer- typelize_from Spree::Product- typelize purchasable: :boolean, in_stock: :boolean, price: 'number | null'-- attributes :id, :name, :description, :slug- attributes available_on: :iso8601, created_at: :iso8601-- attribute :price do |product|- product.default_variant.price&.to_f- end-- many :variants,- resource: Spree.api.variant_serializer,- if: proc { params[:includes]&.include?('variants') }- end- end- end-end-```--**Creating an Admin Serializer:**--```ruby-module Spree- module Api- module V3- module Admin- class ProductSerializer < V3::ProductSerializer- typelize_from Spree::Product- typelize cost_price: 'number | null',- private_metadata: 'Record<string, unknown> | null'-- attributes :status, :cost_price, :private_metadata-- # Override to use admin variant serializer- many :variants,- resource: Spree::Api::V3::Admin::VariantSerializer,- if: proc { params[:includes]&.include?('variants') }- end- end- end- end-end-```--### Typelizer DSL--- Don't use `typelize_from` for serializers, please use `typelize` instead for each attribute-- `typelize attr: :type` - Define types for computed/delegated attributes not on the model-- Type formats: `:string`, `:boolean`, `:number`, `'string | null'`, `'string[]'`, `'Record<string, unknown>'`--### TypeScript Type Generation--Types are generated to `sdk/src/types/generated/`:--```bash-# Generate types-bundle exec rake typelizer:generate-```--Naming convention:-- Store serializers -> `Store{Name}` (e.g., `StoreProduct`)-- Admin serializers -> `Admin{Name}` (e.g., `AdminProduct`)--### Controllers--**Store API Controllers:**--```ruby-module Spree- module Api- module V3- class ProductsController < BaseController- def index- products = current_store.products.available- render json: serialize(products)- end-- def show- product = current_store.products.find_by!(slug: params[:id])- render json: serialize(product)- end-- private-- def serialize(resource, options = {})- serializer_class.new(resource, serializer_params.merge(options)).serialize- end-- def serializer_class- Spree.api.product_serializer.constantize- end-- def serializer_params- {- params: {- store: current_store,- currency: current_currency,- includes: include_params- }- }- end- end- end- end-end-```--**Admin API Controllers:**--```ruby-module Spree- module Api- module V3- module Admin- class ProductsController < AdminController- def index- products = scope.ransack(params[:q]).result- render json: serialize(products)- end-- private-- def scope- Spree::Product.accessible_by(current_ability)- end-- def serializer_class- Spree::Api::V3::Admin::ProductSerializer- end- end- end- end- end-end-```--### API Key Authentication--API v3 uses `Spree::ApiKey` for authentication:--- **Publishable keys** (`spree_pk_xxx`) - Store API, rate-limited-- **Secret keys** (`spree_sk_xxx`) - Admin API, full access--```ruby-# In controllers-before_action :authenticate_api_key!--def current_api_key- @current_api_key ||= Spree::ApiKey.find_by(key: bearer_token)-end--def admin_context?- current_api_key&.admin?-end-```--### Testing--**Request Specs:**--```ruby-RSpec.describe 'Products API', type: :request do- let(:store) { create(:store) }- let(:api_key) { create(:api_key, scope: 'store', store: store) }- let(:headers) { { 'Authorization' => "Bearer #{api_key.key}" } }-- describe 'GET /api/v3/products' do- it 'returns products' do- product = create(:product, stores: [store])-- get '/api/v3/products', headers: headers-- expect(response).to have_http_status(:ok)- expect(json_response['data'].first['id']).to eq(product.id)- end- end-end-```--### OpenAPI Specification--API specs are documented using rswag:--```ruby-# spec/integration/api/v3/products_spec.rb-RSpec.describe 'Products API', type: :request do- path '/api/v3/products' do- get 'List products' do- tags 'Products'- produces 'application/json'-- response '200', 'products found' do- schema type: :object,- properties: {- data: { type: :array, items: { '$ref' => '#/components/schemas/StoreProduct' } }- }- run_test!- end- end- end-end-```--Generate OpenAPI spec:--```bash-bundle exec rake rswag:specs:swaggerize-```--## File Locations--- Controllers: `app/controllers/spree/api/v3/`-- Serializers: `app/serializers/spree/api/v3/`-- Request specs: `spec/requests/spree/api/v3/`-- Integration specs (rswag): `spec/integration/spree/api/v3/`-- Generated types: `sdk/src/types/generated/`diff --git a/api/app/serializers/spree/api/v3/admin/price_serializer.rb b/api/app/serializers/spree/api/v3/admin/price_serializer.rbindex 80b5df1c19..29ad52f032 100644--- a/api/app/serializers/spree/api/v3/admin/price_serializer.rb+++ b/api/app/serializers/spree/api/v3/admin/price_serializer.rb@@ -5,8 +5,9 @@ module Spree# Admin API Price Serializer# Extends Store Price Serializer with admin-only fieldsclass PriceSerializer < V3::PriceSerializer- typelize_from Spree::Price- typelize variant_id: 'string | null'+ typelize variant_id: 'string | null',+ created_at: :string,+ updated_at: :stringattribute :variant_id do |price|price&.variant&.prefix_id