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
feat(api): store Collection read API (index, show, PLP)
Łukasz Adamczykee2924445ebc
diff --git a/spree/api/app/controllers/spree/api/v3/store/collections/products_controller.rb b/spree/api/app/controllers/spree/api/v3/store/collections/products_controller.rbnew file mode 100644index 0000000000..622e0b518f--- /dev/null+++ b/spree/api/app/controllers/spree/api/v3/store/collections/products_controller.rb@@ -0,0 +1,57 @@+module Spree+ module Api+ module V3+ module Store+ module Collections+ # Dedicated collection PLP. Reuses the ProductsController search flow;+ # the collection is applied as an `in_collection` filter (not an AR+ # pre-scope, so Meilisearch's own filtering/counting/pagination works),+ # and the collection's sort_order is the default when the request omits `sort`.+ class ProductsController < Spree::Api::V3::Store::ProductsController+ protected++ def collection+ return @collection if @collection.present?++ result = search_provider.search_and_filter(+ scope: scope.includes(collection_includes).preload_associations_lazily.accessible_by(current_ability, :show),+ query: search_query,+ filters: (search_filters || {}).merge('in_collection' => current_collection.prefixed_id),+ sort: sort_param.presence || collection_default_sort,+ page: page,+ limit: limit+ )++ @pagy = result.pagy+ @collection = result.products+ end++ private++ # The collection's sort_order rendered in the API sort format+ # (e.g. 'price asc' -> 'price') — the PLP default when `sort` is omitted.+ def collection_default_sort+ sort_order = current_collection.sort_order+ return sort_order unless sort_order.to_s.include?(' ')++ field, direction = sort_order.split(' ', 2)+ direction == 'desc' ? "-#{field}" : field+ end++ # Resolve by permalink or prefixed ID, mirroring CollectionsController#find_resource.+ def current_collection+ @current_collection ||= begin+ id = params[:collection_id]+ if id.to_s.start_with?('coll_')+ current_store.collections.find_by_prefix_id!(id)+ else+ current_store.collections.i18n.find_by!(permalink: id)+ end+ end+ end+ end+ end+ end+ end+ end+enddiff --git a/spree/api/app/controllers/spree/api/v3/store/collections_controller.rb b/spree/api/app/controllers/spree/api/v3/store/collections_controller.rbnew file mode 100644index 0000000000..db0e1c45fb--- /dev/null+++ b/spree/api/app/controllers/spree/api/v3/store/collections_controller.rb@@ -0,0 +1,32 @@+module Spree+ module Api+ module V3+ module Store+ class CollectionsController < ResourceController+ include Spree::Api::V3::HttpCaching++ protected++ def model_class+ Spree::Collection+ end++ def serializer_class+ Spree.api.collection_serializer+ end++ # Find by permalink or prefixed ID (SEO-friendly URLs), i18n-scoped with a+ # fallback to the default locale — mirrors the Categories controller.+ def find_resource+ id = params[:id]+ if id.to_s.start_with?('coll_')+ scope.find_by_prefix_id!(id)+ else+ find_with_fallback_default_locale { scope.i18n.find_by!(permalink: id) }+ end+ end+ end+ end+ end+ end+enddiff --git a/spree/api/app/serializers/spree/api/v3/collection_serializer.rb b/spree/api/app/serializers/spree/api/v3/collection_serializer.rbnew file mode 100644index 0000000000..1e52160930--- /dev/null+++ b/spree/api/app/serializers/spree/api/v3/collection_serializer.rb@@ -0,0 +1,41 @@+module Spree+ module Api+ module V3+ # Store (customer-facing) collection serializer. Deliberately omits the+ # merchandising config — automatic / rules_match_policy / rules — which is+ # back-office state exposed only by the Admin serializer.+ class CollectionSerializer < BaseSerializer+ typelize name: :string, permalink: :string, position: :number,+ sort_order: :string, hide_from_nav: :boolean,+ meta_title: [:string, nullable: true], meta_description: [:string, nullable: true], meta_keywords: [:string, nullable: true],+ description: :string, description_html: :string,+ image_url: [:string, nullable: true], square_image_url: [:string, nullable: true],+ products_count: :number++ attributes :name, :permalink, :position, :sort_order, :hide_from_nav,+ :meta_title, :meta_description, :meta_keywords, :products_count++ attribute :description do |collection|+ collection.description&.to_plain_text.to_s+ end++ attribute :description_html do |collection|+ collection.description&.body&.to_s.to_s+ end++ attribute :image_url do |collection|+ image_url_for(collection.image)+ end++ attribute :square_image_url do |collection|+ image_url_for(collection.square_image)+ end++ many :public_metafields,+ key: :custom_fields,+ resource: proc { Spree.api.custom_field_serializer },+ if: proc { expand?('custom_fields') }+ end+ end+ end+enddiff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rbindex 861771f1b4..1a4fb9f132 100644--- a/spree/api/config/routes.rb+++ b/spree/api/config/routes.rb@@ -27,6 +27,9 @@ Spree::Core::Engine.add_routes doendendresources :categories, only: [:index, :show], id: /.+/+ resources :collections, only: [:index, :show] do+ resources :products, controller: 'collections/products', only: [:index]+ end# Cartsresources :carts, only: [:index, :show, :create, :update, :destroy] dodiff --git a/spree/api/lib/spree/api/dependencies.rb b/spree/api/lib/spree/api/dependencies.rbindex 25988cbbe9..75a813b842 100644--- a/spree/api/lib/spree/api/dependencies.rb+++ b/spree/api/lib/spree/api/dependencies.rb@@ -127,6 +127,7 @@ module Spreedelivery_rate_serializer: 'Spree::Api::V3::DeliveryRateSerializer',stock_location_serializer: 'Spree::Api::V3::StockLocationSerializer',category_serializer: 'Spree::Api::V3::CategorySerializer',+ collection_serializer: 'Spree::Api::V3::CollectionSerializer',discount_serializer: 'Spree::Api::V3::DiscountSerializer',digital_link_serializer: 'Spree::Api::V3::DigitalLinkSerializer',gift_card_serializer: 'Spree::Api::V3::GiftCardSerializer',diff --git a/spree/api/spec/controllers/spree/api/v3/store/collections/products_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/collections/products_controller_spec.rbnew file mode 100644index 0000000000..967c68059f--- /dev/null+++ b/spree/api/spec/controllers/spree/api/v3/store/collections/products_controller_spec.rb@@ -0,0 +1,40 @@+require 'spec_helper'++RSpec.describe Spree::Api::V3::Store::Collections::ProductsController, type: :controller do+ render_views++ include_context 'API v3 Store'++ let!(:collection) { create(:collection, store: store) }+ let!(:in_product) { create(:product, status: 'active') }+ let!(:out_product) { create(:product, status: 'active') }++ before do+ request.headers['X-Spree-Api-Key'] = api_key.token+ Spree::ProductCollection.create!(collection: collection, product: in_product)+ end++ describe 'GET #index' do+ it 'returns only products in the collection' do+ get :index, params: { collection_id: collection.prefixed_id }++ expect(response).to have_http_status(:ok)+ ids = json_response['data'].pluck('id')+ expect(ids).to include(in_product.prefixed_id)+ expect(ids).not_to include(out_product.prefixed_id)+ end++ it 'resolves the collection by permalink' do+ get :index, params: { collection_id: collection.permalink }++ expect(response).to have_http_status(:ok)+ expect(json_response['data'].pluck('id')).to include(in_product.prefixed_id)+ end++ it 'returns not found for an unknown collection' do+ get :index, params: { collection_id: 'coll_nope' }++ expect(response).to have_http_status(:not_found)+ end+ end+enddiff --git a/spree/api/spec/controllers/spree/api/v3/store/collections_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/collections_controller_spec.rbnew file mode 100644index 0000000000..7d209df872--- /dev/null+++ b/spree/api/spec/controllers/spree/api/v3/store/collections_controller_spec.rb@@ -0,0 +1,70 @@+require 'spec_helper'++RSpec.describe Spree::Api::V3::Store::CollectionsController, type: :controller do+ render_views++ include_context 'API v3 Store'++ let!(:collection) { create(:collection, store: store, name: 'Summer Sale') }+ let!(:other_store) { create(:store) }+ let!(:other_collection) { create(:collection, store: other_store) }++ before { request.headers['X-Spree-Api-Key'] = api_key.token }++ describe 'GET #index' do+ it 'returns collections for the current store only' do+ get :index++ expect(response).to have_http_status(:ok)+ ids = json_response['data'].pluck('id')+ expect(ids).to include(collection.prefixed_id)+ expect(ids).not_to include(other_collection.prefixed_id)+ end++ it 'exposes customer-facing attributes but not the merchandising config' do+ get :index++ data = json_response['data'].find { |c| c['id'] == collection.prefixed_id }+ expect(data).to include('name', 'permalink', 'sort_order', 'products_count', 'description', 'image_url')+ expect(data).not_to include('automatic', 'rules_match_policy', 'rules')+ end++ context 'without API key' do+ before { request.headers['X-Spree-Api-Key'] = nil }++ it 'returns unauthorized' do+ get :index+ expect(response).to have_http_status(:unauthorized)+ end+ end+ end++ describe 'GET #show' do+ it 'finds by permalink' do+ get :show, params: { id: collection.permalink }++ expect(response).to have_http_status(:ok)+ expect(json_response['id']).to eq(collection.prefixed_id)+ expect(json_response['name']).to eq('Summer Sale')+ end++ it 'finds by prefixed id' do+ get :show, params: { id: collection.prefixed_id }++ expect(response).to have_http_status(:ok)+ expect(json_response['id']).to eq(collection.prefixed_id)+ end++ it 'omits the merchandising config' do+ get :show, params: { id: collection.prefixed_id }++ expect(json_response).not_to include('automatic', 'rules_match_policy', 'rules')+ end++ it "returns not found for another store's collection" do+ get :show, params: { id: other_collection.permalink }++ expect(response).to have_http_status(:not_found)+ end+ end+enddiff --git a/spree/core/app/models/spree/permission_sets/default_customer.rb b/spree/core/app/models/spree/permission_sets/default_customer.rbindex 4fbb6a8f16..4c92404e96 100644--- a/spree/core/app/models/spree/permission_sets/default_customer.rb+++ b/spree/core/app/models/spree/permission_sets/default_customer.rb@@ -11,6 +11,7 @@ module Spreeclass DefaultCustomer < Basedef activate!# Read-only access to catalog+ can :read, Spree::Collectioncan :read, Spree::Countrycan :read, Spree::OptionTypecan :read, Spree::OptionValuediff --git a/spree/core/app/models/spree/permission_sets/product_display.rb b/spree/core/app/models/spree/permission_sets/product_display.rbindex 43e4805f56..505fe1f100 100644--- a/spree/core/app/models/spree/permission_sets/product_display.rb+++ b/spree/core/app/models/spree/permission_sets/product_display.rb@@ -15,6 +15,7 @@ module Spreecan [:read, :admin], Spree::OptionTypecan [:read, :admin], Spree::OptionValuecan [:read, :admin], Spree::Metafield+ can [:read, :admin], Spree::Collectioncan [:read, :admin], Spree::Taxoncan [:read, :admin], Spree::Taxonomycan [:read, :admin], Spree::Classification