Skip to content

armgit / spree

Public Imported from GitHub
0

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.

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.rb
new file mode 100644
index 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
+end
diff --git a/spree/api/app/controllers/spree/api/v3/store/collections_controller.rb b/spree/api/app/controllers/spree/api/v3/store/collections_controller.rb
new file mode 100644
index 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
+end
diff --git a/spree/api/app/serializers/spree/api/v3/collection_serializer.rb b/spree/api/app/serializers/spree/api/v3/collection_serializer.rb
new file mode 100644
index 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
+end
diff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rb
index 861771f1b4..1a4fb9f132 100644
--- a/spree/api/config/routes.rb
+++ b/spree/api/config/routes.rb
@@ -27,6 +27,9 @@ Spree::Core::Engine.add_routes do
end
end
resources :categories, only: [:index, :show], id: /.+/
+ resources :collections, only: [:index, :show] do
+ resources :products, controller: 'collections/products', only: [:index]
+ end
# Carts
resources :carts, only: [:index, :show, :create, :update, :destroy] do
diff --git a/spree/api/lib/spree/api/dependencies.rb b/spree/api/lib/spree/api/dependencies.rb
index 25988cbbe9..75a813b842 100644
--- a/spree/api/lib/spree/api/dependencies.rb
+++ b/spree/api/lib/spree/api/dependencies.rb
@@ -127,6 +127,7 @@ module Spree
delivery_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.rb
new file mode 100644
index 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
+end
diff --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.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/app/models/spree/permission_sets/default_customer.rb b/spree/core/app/models/spree/permission_sets/default_customer.rb
index 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 Spree
class DefaultCustomer < Base
def activate!
# Read-only access to catalog
+ can :read, Spree::Collection
can :read, Spree::Country
can :read, Spree::OptionType
can :read, Spree::OptionValue
diff --git a/spree/core/app/models/spree/permission_sets/product_display.rb b/spree/core/app/models/spree/permission_sets/product_display.rb
index 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 Spree
can [:read, :admin], Spree::OptionType
can [:read, :admin], Spree::OptionValue
can [:read, :admin], Spree::Metafield
+ can [:read, :admin], Spree::Collection
can [:read, :admin], Spree::Taxon
can [:read, :admin], Spree::Taxonomy
can [:read, :admin], Spree::Classification