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
Implement Taxons & Taxonomies in API and SDK
Damian Legawiec47cf3e023ef2
diff --git a/admin/app/helpers/spree/admin/sortable_tree_helper.rb b/admin/app/helpers/spree/admin/sortable_tree_helper.rbindex eaa3e5eda6..53dd1d64c0 100644--- a/admin/app/helpers/spree/admin/sortable_tree_helper.rb+++ b/admin/app/helpers/spree/admin/sortable_tree_helper.rb@@ -23,7 +23,7 @@ module Spreeclass: 'sortable-tree-item draggable',data: {sortable_tree_resource_name_value: :taxon,- sortable_tree_update_url_value: spree.reposition_admin_taxonomy_taxon_path(child_resource.taxonomy_id, child_resource.id)+ sortable_tree_update_url_value: spree.reposition_admin_taxonomy_taxon_path(child_resource.taxonomy, child_resource)})endenddiff --git a/admin/app/views/spree/admin/shared/sortable_tree/_taxonomy.html.erb b/admin/app/views/spree/admin/shared/sortable_tree/_taxonomy.html.erbindex edea8b8a5b..dbd6da609b 100644--- a/admin/app/views/spree/admin/shared/sortable_tree/_taxonomy.html.erb+++ b/admin/app/views/spree/admin/shared/sortable_tree/_taxonomy.html.erb@@ -27,7 +27,7 @@</div><div class="flex items-center px-3 ml-3 gap-2">- <%= link_to_edit(taxon, url: spree.edit_admin_taxonomy_taxon_path(taxonomy, taxon.id), data: { row_link_target: :link, turbo_frame: '_top' }) if can?(:edit, taxon) %>+ <%= link_to_edit(taxon, url: spree.edit_admin_taxonomy_taxon_path(taxonomy, taxon), data: { row_link_target: :link, turbo_frame: '_top' }) if can?(:edit, taxon) %><%= dropdown class: 'h-full' do %><%= dropdown_toggle class: 'btn-sm btn-light px-1 h-full' do %>@@ -38,7 +38,7 @@<%= link_to_with_icon 'plus', Spree.t(:new_nested_taxon), spree.new_admin_taxonomy_taxon_path(taxonomy, taxon: { parent_id: taxon.id }), class: 'dropdown-item' %><div class="dropdown-divider"></div><% end %>- <%= link_to_delete(taxon, icon: 'trash', url: spree.admin_taxonomy_taxon_path(taxonomy, taxon.id), class: 'dropdown-item text-red-600 hover:bg-red-100') if can?(:destroy, taxon) %>+ <%= link_to_delete(taxon, icon: 'trash', url: spree.admin_taxonomy_taxon_path(taxonomy, taxon), class: 'dropdown-item text-red-600 hover:bg-red-100') if can?(:destroy, taxon) %><% end %><% end %></div>diff --git a/admin/app/views/spree/admin/taxonomies/show.html.erb b/admin/app/views/spree/admin/taxonomies/show.html.erbindex b1f090fae1..c74be67e8a 100644--- a/admin/app/views/spree/admin/taxonomies/show.html.erb+++ b/admin/app/views/spree/admin/taxonomies/show.html.erb@@ -8,7 +8,7 @@<% end if can?(:create, Spree::Taxon) %><% content_for :page_actions_dropdown do %>- <%= link_to_edit(@taxonomy.root, url: spree.edit_admin_taxonomy_taxon_path(@taxonomy, @taxonomy.root.id), class: 'text-left dropdown-item') %>+ <%= link_to_edit(@taxonomy.root, url: spree.edit_admin_taxonomy_taxon_path(@taxonomy, @taxonomy.root), class: 'text-left dropdown-item') %><% end if can?(:edit, @taxonomy) %><div id="sortableTreeArea">diff --git a/admin/app/views/spree/admin/taxons/edit.html.erb b/admin/app/views/spree/admin/taxons/edit.html.erbindex 7310d82188..bc669a721c 100644--- a/admin/app/views/spree/admin/taxons/edit.html.erb+++ b/admin/app/views/spree/admin/taxons/edit.html.erb@@ -7,8 +7,7 @@<%= external_page_preview_link(@taxon, name: Spree.t(:taxonomy)) %><% end %>-<%# Because otherwise the form would attempt to use to_param of @taxon %>-<% form_url = admin_taxonomy_taxon_path(@taxonomy.id, @taxon.id) %>+<% form_url = admin_taxonomy_taxon_path(@taxonomy, @taxon) %><%= render partial: 'spree/admin/shared/error_messages', locals: { target: @taxon } %>diff --git a/api/app/controllers/spree/api/v3/store/taxons/products_controller.rb b/api/app/controllers/spree/api/v3/store/taxons/products_controller.rbnew file mode 100644index 0000000000..2df3dea882--- /dev/null+++ b/api/app/controllers/spree/api/v3/store/taxons/products_controller.rb@@ -0,0 +1,44 @@+module Spree+ module Api+ module V3+ module Store+ module Taxons+ class ProductsController < Store::ProductsController+ before_action :set_taxon++ protected++ def set_taxon+ @taxon = find_taxon+ end++ def scope+ Spree::Product.+ in_taxon(@taxon).+ for_store(current_store).+ accessible_by(current_ability, :show).+ available(Time.current, Spree::Current.currency).+ includes(scope_includes).+ preload_associations_lazily.+ i18n+ end++ private++ def find_taxon+ id = params[:taxon_id]+ taxon_scope = Spree::Taxon.for_store(current_store).accessible_by(current_ability, :show)+ taxon_scope = taxon_scope.i18n if Spree::Taxon.include?(Spree::TranslatableResource)++ if id.to_s.start_with?('txn_')+ taxon_scope.find_by!(prefix_id: id)+ else+ find_with_fallback_default_locale { taxon_scope.i18n.find_by!(permalink: id) }+ end+ end+ end+ end+ end+ end+ end+enddiff --git a/api/app/controllers/spree/api/v3/store/taxons_controller.rb b/api/app/controllers/spree/api/v3/store/taxons_controller.rbindex 2540fa8ccf..3ea6ea372d 100644--- a/api/app/controllers/spree/api/v3/store/taxons_controller.rb+++ b/api/app/controllers/spree/api/v3/store/taxons_controller.rb@@ -23,6 +23,10 @@ module Spreefind_with_fallback_default_locale { scope.i18n.find_by!(permalink: id) }endend++ def collection_includes+ [:taxonomy]+ endendendenddiff --git a/api/app/serializers/spree/api/v3/admin/taxon_serializer.rb b/api/app/serializers/spree/api/v3/admin/taxon_serializer.rbindex 8530e6eb74..51ed38b101 100644--- a/api/app/serializers/spree/api/v3/admin/taxon_serializer.rb+++ b/api/app/serializers/spree/api/v3/admin/taxon_serializer.rb@@ -5,6 +5,11 @@ module Spree# Admin API Taxon Serializer# Full taxon data including admin-only fieldsclass TaxonSerializer < V3::TaxonSerializer+ typelize lft: :number, rgt: :number++ # Nested set columns for tree operations+ attributes :lft, :rgt+many :metafields,resource: Spree::Api::V3::Admin::MetafieldSerializer,if: proc { params[:includes]&.include?('metafields') }diff --git a/api/app/serializers/spree/api/v3/base_serializer.rb b/api/app/serializers/spree/api/v3/base_serializer.rbindex 3302449dfb..285e7e21c2 100644--- a/api/app/serializers/spree/api/v3/base_serializer.rb+++ b/api/app/serializers/spree/api/v3/base_serializer.rb@@ -75,9 +75,11 @@ module Spreeenddef image_url_for(image)- return nil unless image&.attachment&.attached?+ return nil if image.nil?+ return nil unless image.respond_to?(:attached?) && image.attached?- Rails.application.routes.url_helpers.cdn_image_url(image.attachment)+ # cdn_image_url expects an attachment (with .blob method), not a raw blob+ Rails.application.routes.url_helpers.cdn_image_url(image)endendenddiff --git a/api/app/serializers/spree/api/v3/product_serializer.rb b/api/app/serializers/spree/api/v3/product_serializer.rbindex 047b398789..d23733583a 100644--- a/api/app/serializers/spree/api/v3/product_serializer.rb+++ b/api/app/serializers/spree/api/v3/product_serializer.rb@@ -89,7 +89,8 @@ module Spreetaxons.select { |t| t.taxonomy.store_id == params[:store].id }},resource: Spree.api.taxon_serializer,- if: proc { params[:includes]&.include?('taxons') }+ if: proc { params[:includes]&.include?('taxons') },+ params: { includes: [] }many :public_metafields,key: :metafields,diff --git a/api/app/serializers/spree/api/v3/taxon_serializer.rb b/api/app/serializers/spree/api/v3/taxon_serializer.rbindex 48af5dfc01..7a0710760a 100644--- a/api/app/serializers/spree/api/v3/taxon_serializer.rb+++ b/api/app/serializers/spree/api/v3/taxon_serializer.rb@@ -2,15 +2,14 @@ module Spreemodule Apimodule V3class TaxonSerializer < BaseSerializer- typelize name: :string, permalink: :string, position: :number,- lft: :number, rgt: :number, depth: :number,+ typelize name: :string, permalink: :string, position: :number, depth: :number,meta_title: 'string | null', meta_description: 'string | null', meta_keywords: 'string | null',parent_id: 'string | null', taxonomy_id: :string, children_count: :number,description: :string, description_html: :string,image_url: 'string | null', square_image_url: 'string | null',is_root: :boolean, is_child: :boolean, is_leaf: :boolean- attributes :name, :permalink, :position, :lft, :rgt, :depth,+ attributes :name, :permalink, :position, :depth,:meta_title, :meta_description, :meta_keywords,:children_count,created_at: :iso8601, updated_at: :iso8601@@ -24,11 +23,11 @@ module Spreeendattribute :description do |taxon|- taxon.description.to_plain_text+ taxon.description&.to_plain_text.to_sendattribute :description_html do |taxon|- taxon.description.to_s+ taxon.description&.body&.to_s.to_sendattribute :image_url do |taxon|@@ -52,13 +51,22 @@ module Spreeend# Conditional associations+ # Note: We pass empty includes to nested taxons to prevent infinite recursion+ # (e.g., ancestors trying to load their own ancestors)one :parent,resource: Spree.api.taxon_serializer,- if: proc { params[:includes]&.include?('parent') }+ if: proc { params[:includes]&.include?('parent') },+ params: { includes: [] }many :children,resource: Spree.api.taxon_serializer,- if: proc { params[:includes]&.include?('children') }+ if: proc { params[:includes]&.include?('children') },+ params: { includes: [] }++ many :ancestors,+ resource: Spree.api.taxon_serializer,+ if: proc { params[:includes]&.include?('ancestors') },+ params: { includes: [] }many :public_metafields,key: :metafields,diff --git a/api/app/serializers/spree/api/v3/taxonomy_serializer.rb b/api/app/serializers/spree/api/v3/taxonomy_serializer.rbindex 4e4bd70cc8..f21141e159 100644--- a/api/app/serializers/spree/api/v3/taxonomy_serializer.rb+++ b/api/app/serializers/spree/api/v3/taxonomy_serializer.rb@@ -2,19 +2,26 @@ module Spreemodule Apimodule V3class TaxonomySerializer < BaseSerializer- typelize name: :string, position: :number+ typelize name: :string, position: :number, root_id: 'string | null'attributes :name, :position,created_at: :iso8601, updated_at: :iso8601+ attribute :root_id do |taxonomy|+ taxonomy.root&.prefix_id+ end+# Conditional associations+ # Note: We pass empty includes to nested taxons to prevent infinite recursionone :root,resource: Spree.api.taxon_serializer,- if: proc { params[:includes]&.include?('root') }+ if: proc { params[:includes]&.include?('root') },+ params: { includes: [] }many :taxons,resource: Spree.api.taxon_serializer,- if: proc { params[:includes]&.include?('taxons') }+ if: proc { params[:includes]&.include?('taxons') },+ params: { includes: [] }many :public_metafields,key: :metafields,diff --git a/api/config/routes.rb b/api/config/routes.rbindex e4119feda7..88c60a24e6 100644--- a/api/config/routes.rb+++ b/api/config/routes.rb@@ -17,7 +17,9 @@ Spree::Core::Engine.add_routes do# Catalogresources :products, only: [:index, :show]resources :taxonomies, only: [:index, :show]- resources :taxons, only: [:show], id: /.+/+ resources :taxons, only: [:index, :show], id: /.+/ do+ resources :products, only: [:index], controller: 'taxons/products'+ end# Ordersresources :orders dodiff --git a/api/spec/controllers/spree/api/v3/store/taxonomies_controller_spec.rb b/api/spec/controllers/spree/api/v3/store/taxonomies_controller_spec.rbindex 83c440ae87..226d1d22a0 100644--- a/api/spec/controllers/spree/api/v3/store/taxonomies_controller_spec.rb+++ b/api/spec/controllers/spree/api/v3/store/taxonomies_controller_spec.rb@@ -71,6 +71,12 @@ RSpec.describe Spree::Api::V3::Store::TaxonomiesController, type: :controller doexpect(json_response['name']).to be_presentend+ it 'returns root_id for quick access to root taxon' do+ get :show, params: { id: taxonomy.prefix_id }++ expect(json_response['root_id']).to eq(taxonomy.root.prefix_id)+ end+context 'error handling' doit 'returns not found for non-existent taxonomy' doget :show, params: { id: 'txnmy_nonexistent' }diff --git a/api/spec/controllers/spree/api/v3/store/taxons/products_controller_spec.rb b/api/spec/controllers/spree/api/v3/store/taxons/products_controller_spec.rbnew file mode 100644index 0000000000..62abcbe401--- /dev/null+++ b/api/spec/controllers/spree/api/v3/store/taxons/products_controller_spec.rb@@ -0,0 +1,101 @@+require 'spec_helper'++RSpec.describe Spree::Api::V3::Store::Taxons::ProductsController, type: :controller do+ render_views++ include_context 'API v3 Store'++ let(:taxonomy) { create(:taxonomy, store: store) }+ let!(:taxon) { create(:taxon, taxonomy: taxonomy) }+ let!(:child_taxon) { create(:taxon, taxonomy: taxonomy, parent: taxon) }++ let!(:product_in_taxon) { create(:product, stores: [store], taxons: [taxon]) }+ let!(:product_in_child_taxon) { create(:product, stores: [store], taxons: [child_taxon]) }+ let!(:product_not_in_taxon) { create(:product, stores: [store]) }++ let!(:other_store) { create(:store) }+ let!(:other_taxonomy) { create(:taxonomy, store: other_store) }+ let!(:other_taxon) { create(:taxon, taxonomy: other_taxonomy) }++ before do+ request.headers['X-Spree-Api-Key'] = api_key.token+ end++ describe 'GET #index' do+ context 'finding taxon by permalink' do+ it 'returns products belonging to the taxon' do+ get :index, params: { taxon_id: taxon.permalink }++ expect(response).to have_http_status(:ok)+ expect(json_response['data'].pluck('id')).to include(product_in_taxon.prefix_id)+ expect(json_response['data'].pluck('id')).not_to include(product_not_in_taxon.prefix_id)+ end++ it 'returns products from descendant taxons' do+ get :index, params: { taxon_id: taxon.permalink }++ expect(response).to have_http_status(:ok)+ # Parent taxon should include products from child taxons+ expect(json_response['data'].pluck('id')).to include(product_in_taxon.prefix_id)+ expect(json_response['data'].pluck('id')).to include(product_in_child_taxon.prefix_id)+ end++ it 'returns only products from the specific child taxon when queried directly' do+ get :index, params: { taxon_id: child_taxon.permalink }++ expect(response).to have_http_status(:ok)+ expect(json_response['data'].pluck('id')).to include(product_in_child_taxon.prefix_id)+ expect(json_response['data'].pluck('id')).not_to include(product_in_taxon.prefix_id)+ end+ end++ context 'finding taxon by prefix_id' do+ it 'returns products belonging to the taxon' do+ get :index, params: { taxon_id: taxon.prefix_id }++ expect(response).to have_http_status(:ok)+ expect(json_response['data'].pluck('id')).to include(product_in_taxon.prefix_id)+ end+ end++ it 'returns pagination metadata' do+ get :index, params: { taxon_id: taxon.permalink }++ expect(json_response['meta']).to include('page', 'limit', 'count', 'pages')+ end++ it 'supports pagination' do+ create_list(:product, 3, stores: [store], taxons: [taxon])++ get :index, params: { taxon_id: taxon.permalink, per_page: 2, page: 1 }++ expect(json_response['data'].size).to eq(2)+ expect(json_response['meta']['page']).to eq(1)+ expect(json_response['meta']['pages']).to be > 1+ end++ context 'error handling' do+ it 'returns not found for non-existent taxon' do+ get :index, params: { taxon_id: 'non-existent' }++ expect(response).to have_http_status(:not_found)+ end++ it 'returns not found for taxon from another store' do+ get :index, params: { taxon_id: other_taxon.permalink }++ expect(response).to have_http_status(:not_found)+ end+ end++ context 'without API key' do+ before { request.headers['X-Spree-Api-Key'] = nil }++ it 'returns unauthorized' do+ get :index, params: { taxon_id: taxon.permalink }++ expect(response).to have_http_status(:unauthorized)+ end+ end+ end+enddiff --git a/api/spec/controllers/spree/api/v3/store/taxons_controller_spec.rb b/api/spec/controllers/spree/api/v3/store/taxons_controller_spec.rbindex 394655060e..f02e01896d 100644--- a/api/spec/controllers/spree/api/v3/store/taxons_controller_spec.rb+++ b/api/spec/controllers/spree/api/v3/store/taxons_controller_spec.rb@@ -8,6 +8,7 @@ RSpec.describe Spree::Api::V3::Store::TaxonsController, type: :controller dolet(:taxonomy) { create(:taxonomy, store: store) }let!(:taxon) { create(:taxon, taxonomy: taxonomy) }let!(:child_taxon) { create(:taxon, taxonomy: taxonomy, parent: taxon) }+ let!(:grandchild_taxon) { create(:taxon, taxonomy: taxonomy, parent: child_taxon) }let!(:other_store) { create(:store) }let!(:other_taxonomy) { create(:taxonomy, store: other_store) }let!(:other_store_taxon) { create(:taxon, taxonomy: other_taxonomy) }@@ -20,6 +21,79 @@ RSpec.describe Spree::Api::V3::Store::TaxonsController, type: :controller doI18n.locale = store.default_localeend+ describe 'GET #index' do+ it 'returns taxons for the current store' do+ get :index++ expect(response).to have_http_status(:ok)+ expect(json_response['data'].pluck('id')).to include(taxon.prefix_id, child_taxon.prefix_id)+ expect(json_response['data'].pluck('id')).not_to include(other_store_taxon.prefix_id)+ end++ it 'returns pagination metadata' do+ get :index++ expect(json_response['meta']).to include('page', 'limit', 'count', 'pages')+ end++ it 'returns taxon attributes' do+ get :index++ taxon_data = json_response['data'].find { |t| t['id'] == taxon.prefix_id }+ expect(taxon_data).to include('name', 'permalink', 'position', 'depth')+ expect(taxon_data).to include('taxonomy_id', 'parent_id', 'children_count')+ expect(taxon_data).not_to include('lft', 'rgt')+ end++ context 'with images' do+ let!(:taxon_with_image) { create(:taxon, :with_header_image, taxonomy: taxonomy) }++ it 'returns image URLs' do+ get :index++ taxon_data = json_response['data'].find { |t| t['id'] == taxon_with_image.prefix_id }+ expect(taxon_data['image_url']).to be_present+ end+ end++ context 'filtering' do+ it 'filters by taxonomy_id' do+ other_taxonomy_in_store = create(:taxonomy, store: store)+ other_taxon = create(:taxon, taxonomy: other_taxonomy_in_store)++ get :index, params: { q: { taxonomy_id_eq: taxonomy.id } }++ ids = json_response['data'].pluck('id')+ expect(ids).to include(taxon.prefix_id)+ expect(ids).not_to include(other_taxon.prefix_id)+ end++ it 'filters by depth' do+ get :index, params: { q: { depth_eq: grandchild_taxon.depth } }++ ids = json_response['data'].pluck('id')+ expect(ids).to include(grandchild_taxon.prefix_id)+ end++ it 'filters by parent_id' do+ get :index, params: { q: { parent_id_eq: child_taxon.id } }++ ids = json_response['data'].pluck('id')+ expect(ids).to include(grandchild_taxon.prefix_id)+ end+ 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' docontext 'finding by permalink' doit 'returns the taxon by permalink' do@@ -64,6 +138,42 @@ RSpec.describe Spree::Api::V3::Store::TaxonsController, type: :controller doexpect(json_response['parent_id']).to eq(taxon.prefix_id)end+ it 'does not include lft and rgt in store API' do+ get :show, params: { id: taxon.prefix_id }++ expect(json_response).not_to include('lft', 'rgt')+ end++ context 'with includes=ancestors' do+ it 'returns ancestors for breadcrumbs' do+ get :show, params: { id: grandchild_taxon.prefix_id, includes: 'ancestors' }++ expect(response).to have_http_status(:ok)+ expect(json_response['ancestors']).to be_an(Array)+ ancestor_ids = json_response['ancestors'].pluck('id')+ expect(ancestor_ids).to include(taxon.prefix_id, child_taxon.prefix_id)+ end++ it 'returns empty ancestors for root taxon' do+ root_taxon = taxonomy.root++ get :show, params: { id: root_taxon.prefix_id, includes: 'ancestors' }++ expect(response).to have_http_status(:ok)+ expect(json_response['ancestors']).to eq([])+ end+ end++ context 'with includes=children' do+ it 'returns children' do+ get :show, params: { id: taxon.prefix_id, includes: 'children' }++ expect(response).to have_http_status(:ok)+ expect(json_response['children']).to be_an(Array)+ expect(json_response['children'].pluck('id')).to include(child_taxon.prefix_id)+ end+ end+context 'with translations', if: Spree::Taxon.include?(Spree::TranslatableResource) dolet!(:translated_taxon) docreate(:taxon, taxonomy: taxonomy, name: 'Clothing', permalink: 'clothing').tap do |t|diff --git a/sdk/README.md b/sdk/README.mdindex db888969a1..252ac89f70 100644--- a/sdk/README.md+++ b/sdk/README.md@@ -18,38 +18,36 @@ pnpm add @spree/sdkimport { createSpreeClient } from '@spree/sdk';// Initialize the client-const spree = createSpreeClient({+const client = createSpreeClient({baseUrl: 'https://api.mystore.com',apiKey: 'your-publishable-api-key',});// Browse products-const products = await spree.products.list({+const products = await client.products.list({per_page: 10,includes: 'variants,images',});// Get a single product-const product = await spree.products.get('ruby-on-rails-tote');+const product = await client.products.get('ruby-on-rails-tote');// Authentication-const tokens = await spree.auth.login({+const tokens = await client.auth.login({email: '[email protected]',password: 'password123',});-// Create a cart-const cart = await spree.orders.create();--// Add items to cart-await spree.lineItems.create(cart.number, {+// Create a cart and add items+const cart = await client.orders.create();+await client.orders.lineItems.create(cart.id, {variant_id: 'var_abc123',quantity: 2,}, { orderToken: cart.order_token });// Checkout flow-await spree.orders.next(cart.number, { orderToken: cart.order_token });-await spree.orders.complete(cart.number, { orderToken: cart.order_token });+await client.orders.next(cart.id, { orderToken: cart.order_token });+await client.orders.complete(cart.id, { orderToken: cart.order_token });```## Authentication@@ -59,29 +57,29 @@ The SDK supports two authentication modes:### 1. API Key Only (Guest/Public Access)```typescript-const spree = createSpreeClient({+const client = createSpreeClient({baseUrl: 'https://api.mystore.com',apiKey: 'pk_your-publishable-key',});// Public endpoints work without authentication-const products = await spree.products.list();+const products = await client.products.list();```### 2. API Key + JWT (Authenticated Customer)```typescript// Login to get tokens-const tokens = await spree.auth.login({+const tokens = await client.auth.login({email: '[email protected]',password: 'password123',});// Use token for authenticated requests-const orders = await spree.orders.list({}, { token: tokens.access_token });+const orders = await client.orders.list({}, { token: tokens.access_token });// Refresh token when needed-const newTokens = await spree.auth.refresh(tokens.refresh_token);+const newTokens = await client.auth.refresh(tokens.refresh_token);```## Guest Checkout@@ -90,24 +88,24 @@ For guest checkout, use the `order_token` returned when creating an order:```typescript// Create a cart (guest)-const cart = await spree.orders.create();+const cart = await client.orders.create();// Use orderToken for all cart operationsconst options = { orderToken: cart.order_token };// Add items-await spree.lineItems.create(cart.number, {+await client.orders.lineItems.create(cart.id, {variant_id: 'var_abc123',quantity: 1,}, options);// Update order with email-await spree.orders.update(cart.number, {+await client.orders.update(cart.id, {email: '[email protected]',}, options);// Complete checkout-await spree.orders.complete(cart.number, options);+await client.orders.complete(cart.id, options);```## API Reference@@ -116,7 +114,7 @@ await spree.orders.complete(cart.number, options);```typescript// List products with filtering-const products = await spree.products.list({+const products = await client.products.list({page: 1,per_page: 25,'q[name_cont]': 'shirt',@@ -124,33 +122,66 @@ const products = await spree.products.list({});// Get single product by ID or slug-const product = await spree.products.get('ruby-on-rails-tote', {+const product = await client.products.get('ruby-on-rails-tote', {includes: 'variants,images',});```+### Categories (Taxonomies & Taxons)++```typescript+// List taxonomies+const taxonomies = await client.taxonomies.list({+ includes: 'taxons',+});++// Get taxonomy with taxons+const categories = await client.taxonomies.get('tax_123', {+ includes: 'root,taxons',+});++// List taxons with filtering+const taxons = await client.taxons.list({+ 'q[depth_eq]': 1, // Top-level categories only+ 'q[taxonomy_id_eq]': '123', // Filter by taxonomy+});++// Get single taxon by ID or permalink+const taxon = await client.taxons.get('categories/clothing', {+ includes: 'ancestors,children', // For breadcrumbs and subcategories+});++// List products in a category+const categoryProducts = await client.taxons.products.list('categories/clothing', {+ page: 1,+ per_page: 12,+ includes: 'images,default_variant',+});+```+### Cart & Checkout```typescript// Create cart-const cart = await spree.orders.create();+const cart = await client.orders.create();+const options = { orderToken: cart.order_token };// Add item-await spree.lineItems.create(orderId, {+await client.orders.lineItems.create(cart.id, {variant_id: 'var_123',quantity: 2,-});+}, options);// Update item quantity-await spree.lineItems.update(orderId, lineItemId, {+await client.orders.lineItems.update(cart.id, lineItemId, {quantity: 3,-});+}, options);// Remove item-await spree.lineItems.delete(orderId, lineItemId);+await client.orders.lineItems.delete(cart.id, lineItemId, options);// Update order (email, addresses)-await spree.orders.update(orderId, {+await client.orders.update(cart.id, {email: '[email protected]',bill_address_attributes: {firstname: 'John',@@ -159,101 +190,141 @@ await spree.orders.update(orderId, {city: 'New York',zipcode: '10001',phone: '+1 555 123 4567',- country_id: 'ctry_usa',+ country_iso: 'US',},-});+}, options);// Checkout flow-await spree.orders.next(orderId); // Move to next step-await spree.orders.advance(orderId); // Advance through all steps-await spree.orders.complete(orderId); // Complete the order+await client.orders.next(cart.id, options); // Move to next step+await client.orders.advance(cart.id, options); // Advance through all steps+await client.orders.complete(cart.id, options); // Complete the order```### Payments```typescript-// Get available payment methods-const methods = await spree.paymentMethods.list(orderId);--// Create a payment-await spree.payments.create(orderId, {- payment_method_id: 'pm_credit_card',- source_attributes: {- number: '4111111111111111',- month: '12',- year: '2025',- verification_value: '123',- name: 'John Doe',- },-});-```--### Geography+const options = { orderToken: cart.order_token };-```typescript-// List countries-const countries = await spree.countries.list();+// Get available payment methods for an order+const methods = await client.orders.paymentMethods.list(cart.id, options);-// Get country by ISO code-const usa = await spree.countries.get('US');+// List payments on an order+const payments = await client.orders.payments.list(cart.id, options);-// List states for a country-const states = await spree.states.list({ country_id: 'ctry_usa' });+// Get a specific payment+const payment = await client.orders.payments.get(cart.id, paymentId, options);```-### Categories (Taxonomies & Taxons)+### Geography```typescript-// List taxonomies-const taxonomies = await spree.taxonomies.list();+// List countries available for checkout+const countries = await client.countries.list();-// Get taxonomy with taxons-const categories = await spree.taxonomies.get('tax_123', {- includes: 'taxons',-});--// Get single taxon-const taxon = await spree.taxons.get('categories/clothing');+// Get country by ISO code (includes states)+const usa = await client.countries.get('US');+console.log(usa.states); // Array of states```### Customer Account```typescript+const options = { token: tokens.access_token };+// Get profile-const profile = await spree.customer.get({ token });+const profile = await client.customer.get(options);// Update profile-await spree.customer.update({+await client.customer.update({first_name: 'John',last_name: 'Doe',-}, { token });+}, options);-// Manage addresses-const addresses = await spree.addresses.list({}, { token });-await spree.addresses.create({ ... }, { token });-await spree.addresses.update(addressId, { ... }, { token });-await spree.addresses.delete(addressId, { token });+// Manage addresses (nested under customer)+const addresses = await client.customer.addresses.list({}, options);+await client.customer.addresses.create({+ firstname: 'John',+ lastname: 'Doe',+ address1: '123 Main St',+ city: 'New York',+ zipcode: '10001',+ country_iso: 'US',+}, options);+await client.customer.addresses.update(addressId, { city: 'Brooklyn' }, options);+await client.customer.addresses.delete(addressId, options);```### Wishlists```typescript+const options = { token: tokens.access_token };+// List wishlists-const wishlists = await spree.wishlists.list({}, { token });+const wishlists = await client.wishlists.list({}, options);// Create wishlist-const wishlist = await spree.wishlists.create({+const wishlist = await client.wishlists.create({name: 'Birthday Ideas',is_private: true,-}, { token });+}, options);-// Add item to wishlist-await spree.wishlists.addItem(wishlistId, {+// Manage wishlist items (nested under wishlists)+await client.wishlists.items.create(wishlist.id, {variant_id: 'var_123',-}, { token });+ quantity: 1,+}, options);-// Remove item-await spree.wishlists.removeItem(wishlistId, itemId, { token });+await client.wishlists.items.update(wishlist.id, itemId, {+ quantity: 2,+}, options);++await client.wishlists.items.delete(wishlist.id, itemId, options);++// Delete wishlist+await client.wishlists.delete(wishlist.id, options);+```++## Nested Resources++The SDK uses a resource builder pattern (similar to Stripe) for nested resources:++| Parent Resource | Nested Resource | Available Methods |+|-----------------|-----------------|-------------------|+| `orders` | `lineItems` | `create`, `update`, `delete` |+| `orders` | `payments` | `list`, `get` |+| `orders` | `paymentMethods` | `list` |+| `customer` | `addresses` | `list`, `get`, `create`, `update`, `delete` |+| `taxons` | `products` | `list` |+| `wishlists` | `items` | `create`, `update`, `delete` |++Example:+```typescript+// Nested resources follow the pattern: client.parent.nested.method(parentId, ...)+await client.orders.lineItems.create(orderId, params, options);+await client.orders.payments.list(orderId, options);+await client.customer.addresses.list(options);+await client.taxons.products.list(taxonId, params, options);+await client.wishlists.items.create(wishlistId, params, options);+```++## Localization & Currency++Pass locale and currency headers with any request:++```typescript+// Set locale and currency per request+const products = await client.products.list({}, {+ locale: 'fr',+ currency: 'EUR',+});++// Works with all endpoints+const taxon = await client.taxons.get('categories/clothing', {+ includes: 'ancestors',+}, {+ locale: 'de',+ currency: 'EUR',+});```## Error Handling@@ -262,12 +333,13 @@ await spree.wishlists.removeItem(wishlistId, itemId, { token });import { SpreeError } from '@spree/sdk';try {- await spree.products.get('non-existent');+ await client.products.get('non-existent');} catch (error) {if (error instanceof SpreeError) {console.log(error.code); // 'record_not_found'console.log(error.message); // 'Product not found'console.log(error.status); // 404+ console.log(error.details); // Validation errors (if any)}}```@@ -281,12 +353,38 @@ import type {StoreProduct,StoreOrder,StoreVariant,+ StoreTaxon,+ StoreTaxonomy,+ StoreLineItem,PaginatedResponse,} from '@spree/sdk';-const products: PaginatedResponse<StoreProduct> = await spree.products.list();+// All responses are fully typed+const products: PaginatedResponse<StoreProduct> = await client.products.list();+const taxon: StoreTaxon = await client.taxons.get('clothing');```+## Available Types++The SDK exports all Store API types:++- `StoreProduct` - Product data+- `StoreVariant` - Variant data+- `StoreOrder` - Order/cart data+- `StoreLineItem` - Line item in cart+- `StoreTaxonomy` - Category group+- `StoreTaxon` - Individual category+- `StoreCountry` - Country with states+- `StoreAddress` - Customer address+- `StoreUser` - Customer profile+- `StoreWishlist` - Wishlist+- `StoreWishedItem` - Wishlist item+- `StorePayment` - Payment record+- `StorePaymentMethod` - Payment method+- `StoreStore` - Store configuration+- `PaginatedResponse<T>` - Paginated API response+- `AuthTokens` - JWT tokens from login+## LicenseBSD-3-Clausediff --git a/sdk/src/client.ts b/sdk/src/client.tsindex d4dd39bd3d..c17cf2a000 100644--- a/sdk/src/client.ts+++ b/sdk/src/client.ts@@ -6,6 +6,7 @@ import type {PaginatedResponse,ListParams,ProductListParams,+ TaxonListParams,OrderListParams,AddLineItemParams,UpdateLineItemParams,@@ -20,6 +21,7 @@ import type {StorePaymentMethod,StoreStore,StoreWishlist,+ StoreWishedItem,StoreAddress,StoreUser,} from './types';@@ -234,6 +236,18 @@ export class SpreeClient {};readonly taxons = {+ /**+ * List taxons+ */+ list: (+ params?: TaxonListParams,+ options?: RequestOptions+ ): Promise<PaginatedResponse<StoreTaxon>> =>+ this.request<PaginatedResponse<StoreTaxon>>('GET', '/taxons', {+ ...options,+ params: params as Record<string, string | number | undefined>,+ }),+/*** Get a taxon by ID or permalink*/@@ -246,6 +260,29 @@ export class SpreeClient {...options,params,}),++ /**+ * Nested resource: Products in a taxon+ */+ products: {+ /**+ * List products in a taxon+ * @param taxonId - Taxon ID (prefix_id) or permalink+ */+ list: (+ taxonId: string,+ params?: ProductListParams,+ options?: RequestOptions+ ): Promise<PaginatedResponse<StoreProduct>> =>+ this.request<PaginatedResponse<StoreProduct>>(+ 'GET',+ `/taxons/${taxonId}/products`,+ {+ ...options,+ params: params as Record<string, string | number | undefined>,+ }+ ),+ },};// ============================================@@ -356,106 +393,103 @@ export class SpreeClient {options?: RequestOptions): Promise<StoreOrder> =>this.request<StoreOrder>('DELETE', `/orders/${idOrNumber}/store_credits`, options),- };-- // ============================================- // Line Items- // ============================================-- readonly lineItems = {- /**- * Add a line item to an order- */- create: (- orderId: string,- params: AddLineItemParams,- options?: RequestOptions- ): Promise<StoreLineItem> =>- this.request<StoreLineItem>('POST', `/orders/${orderId}/line_items`, {- ...options,- body: params,- }),-- /**- * Update a line item- */- update: (- orderId: string,- lineItemId: string,- params: UpdateLineItemParams,- options?: RequestOptions- ): Promise<StoreLineItem> =>- this.request<StoreLineItem>(- 'PATCH',- `/orders/${orderId}/line_items/${lineItemId}`,- { ...options, body: params }- ),-- /**- * Remove a line item from an order- */- delete: (- orderId: string,- lineItemId: string,- options?: RequestOptions- ): Promise<void> =>- this.request<void>(- 'DELETE',- `/orders/${orderId}/line_items/${lineItemId}`,- options- ),- };-- // ============================================- // Payments- // ============================================-- readonly payments = {- /**- * List payments for an order- */- list: (- orderId: string,- options?: RequestOptions- ): Promise<{ data: StorePayment[]; meta: object }> =>- this.request<{ data: StorePayment[]; meta: object }>(- 'GET',- `/orders/${orderId}/payments`,- options- ),-- /**- * Get a payment by ID- */- get: (- orderId: string,- paymentId: string,- options?: RequestOptions- ): Promise<StorePayment> =>- this.request<StorePayment>(- 'GET',- `/orders/${orderId}/payments/${paymentId}`,- options- ),- };- // ============================================- // Payment Methods- // ============================================-- readonly paymentMethods = {/**- * List available payment methods for an order- */- list: (- orderId: string,- options?: RequestOptions- ): Promise<PaginatedResponse<StorePaymentMethod>> =>- this.request<PaginatedResponse<StorePaymentMethod>>(- 'GET',- `/orders/${orderId}/payment_methods`,- options- ),+ * Nested resource: Line items+ */+ lineItems: {+ /**+ * Add a line item to an order+ */+ create: (+ orderId: string,+ params: AddLineItemParams,+ options?: RequestOptions+ ): Promise<StoreLineItem> =>+ this.request<StoreLineItem>('POST', `/orders/${orderId}/line_items`, {+ ...options,+ body: params,+ }),++ /**+ * Update a line item+ */+ update: (+ orderId: string,+ lineItemId: string,+ params: UpdateLineItemParams,+ options?: RequestOptions+ ): Promise<StoreLineItem> =>+ this.request<StoreLineItem>(+ 'PATCH',+ `/orders/${orderId}/line_items/${lineItemId}`,+ { ...options, body: params }+ ),++ /**+ * Remove a line item from an order+ */+ delete: (+ orderId: string,+ lineItemId: string,+ options?: RequestOptions+ ): Promise<void> =>+ this.request<void>(+ 'DELETE',+ `/orders/${orderId}/line_items/${lineItemId}`,+ options+ ),+ },++ /**+ * Nested resource: Payments+ */+ payments: {+ /**+ * List payments for an order+ */+ list: (+ orderId: string,+ options?: RequestOptions+ ): Promise<{ data: StorePayment[]; meta: object }> =>+ this.request<{ data: StorePayment[]; meta: object }>(+ 'GET',+ `/orders/${orderId}/payments`,+ options+ ),++ /**+ * Get a payment by ID+ */+ get: (+ orderId: string,+ paymentId: string,+ options?: RequestOptions+ ): Promise<StorePayment> =>+ this.request<StorePayment>(+ 'GET',+ `/orders/${orderId}/payments/${paymentId}`,+ options+ ),+ },++ /**+ * Nested resource: Payment methods+ */+ paymentMethods: {+ /**+ * List available payment methods for an order+ */+ list: (+ orderId: string,+ options?: RequestOptions+ ): Promise<PaginatedResponse<StorePaymentMethod>> =>+ this.request<PaginatedResponse<StorePaymentMethod>>(+ 'GET',+ `/orders/${orderId}/payment_methods`,+ options+ ),+ },};// ============================================@@ -480,62 +514,61 @@ export class SpreeClient {...options,body: { user: params },}),- };-- // ============================================- // Addresses- // ============================================- readonly addresses = {/**- * List customer addresses- */- list: (- params?: ListParams,- options?: RequestOptions- ): Promise<PaginatedResponse<StoreAddress>> =>- this.request<PaginatedResponse<StoreAddress>>(- 'GET',- '/customers/me/addresses',- { ...options, params: params as Record<string, string | number | undefined> }- ),-- /**- * Get an address by ID- */- get: (id: string, options?: RequestOptions): Promise<StoreAddress> =>- this.request<StoreAddress>('GET', `/customers/me/addresses/${id}`, options),-- /**- * Create an address- */- create: (- address: Omit<StoreAddress, 'id'>,- options?: RequestOptions- ): Promise<StoreAddress> =>- this.request<StoreAddress>('POST', '/customers/me/addresses', {- ...options,- body: { address },- }),-- /**- * Update an address- */- update: (- id: string,- address: Partial<Omit<StoreAddress, 'id'>>,- options?: RequestOptions- ): Promise<StoreAddress> =>- this.request<StoreAddress>('PATCH', `/customers/me/addresses/${id}`, {- ...options,- body: { address },- }),-- /**- * Delete an address- */- delete: (id: string, options?: RequestOptions): Promise<void> =>- this.request<void>('DELETE', `/customers/me/addresses/${id}`, options),+ * Nested resource: Addresses+ */+ addresses: {+ /**+ * List customer addresses+ */+ list: (+ params?: ListParams,+ options?: RequestOptions+ ): Promise<PaginatedResponse<StoreAddress>> =>+ this.request<PaginatedResponse<StoreAddress>>(+ 'GET',+ '/customers/me/addresses',+ { ...options, params: params as Record<string, string | number | undefined> }+ ),++ /**+ * Get an address by ID+ */+ get: (id: string, options?: RequestOptions): Promise<StoreAddress> =>+ this.request<StoreAddress>('GET', `/customers/me/addresses/${id}`, options),++ /**+ * Create an address+ */+ create: (+ address: Omit<StoreAddress, 'id'>,+ options?: RequestOptions+ ): Promise<StoreAddress> =>+ this.request<StoreAddress>('POST', '/customers/me/addresses', {+ ...options,+ body: { address },+ }),++ /**+ * Update an address+ */+ update: (+ id: string,+ address: Partial<Omit<StoreAddress, 'id'>>,+ options?: RequestOptions+ ): Promise<StoreAddress> =>+ this.request<StoreAddress>('PATCH', `/customers/me/addresses/${id}`, {+ ...options,+ body: { address },+ }),++ /**+ * Delete an address+ */+ delete: (id: string, options?: RequestOptions): Promise<void> =>+ this.request<void>('DELETE', `/customers/me/addresses/${id}`, options),+ },};// ============================================@@ -600,31 +633,51 @@ export class SpreeClient {this.request<void>('DELETE', `/wishlists/${id}`, options),/**- * Add an item to a wishlist- */- addItem: (- wishlistId: string,- params: { variant_id: string; quantity?: number },- options?: RequestOptions- ): Promise<StoreWishlist> =>- this.request<StoreWishlist>('POST', `/wishlists/${wishlistId}/items`, {- ...options,- body: params,- }),-- /**- * Remove an item from a wishlist- */- removeItem: (- wishlistId: string,- itemId: string,- options?: RequestOptions- ): Promise<void> =>- this.request<void>(- 'DELETE',- `/wishlists/${wishlistId}/items/${itemId}`,- options- ),+ * Nested resource: Wishlist items+ */+ items: {+ /**+ * Add an item to a wishlist+ */+ create: (+ wishlistId: string,+ params: { variant_id: string; quantity?: number },+ options?: RequestOptions+ ): Promise<StoreWishedItem> =>+ this.request<StoreWishedItem>('POST', `/wishlists/${wishlistId}/items`, {+ ...options,+ body: params,+ }),++ /**+ * Update a wishlist item+ */+ update: (+ wishlistId: string,+ itemId: string,+ params: { quantity: number },+ options?: RequestOptions+ ): Promise<StoreWishedItem> =>+ this.request<StoreWishedItem>(+ 'PATCH',+ `/wishlists/${wishlistId}/items/${itemId}`,+ { ...options, body: params }+ ),++ /**+ * Remove an item from a wishlist+ */+ delete: (+ wishlistId: string,+ itemId: string,+ options?: RequestOptions+ ): Promise<void> =>+ this.request<void>(+ 'DELETE',+ `/wishlists/${wishlistId}/items/${itemId}`,+ options+ ),+ },};}diff --git a/sdk/src/types/generated/AdminTaxon.ts b/sdk/src/types/generated/AdminTaxon.tsindex 852db417ca..3c382f0ddd 100644--- a/sdk/src/types/generated/AdminTaxon.ts+++ b/sdk/src/types/generated/AdminTaxon.ts@@ -1,4 +1,4 @@-// Typelizer digest accfdf39e8cac79b944e69cf80bfc8c0+// Typelizer digest 623e88e0671ccd41207b1c34f9416829//// DO NOT MODIFY: This file was automatically generated by Typelizer.import type {StoreTaxon, AdminMetafield} from '@/types'@@ -8,8 +8,6 @@ type AdminTaxon = {name: string;permalink: string;position: number;- lft: number;- rgt: number;depth: number;meta_title: string | null;meta_description: string | null;@@ -28,7 +26,10 @@ type AdminTaxon = {is_leaf: boolean;parent?: StoreTaxon;children?: Array<StoreTaxon>;+ ancestors?: Array<StoreTaxon>;metafields?: Array<AdminMetafield>;+ lft: number;+ rgt: number;}export default AdminTaxon;diff --git a/sdk/src/types/generated/AdminTaxonomy.ts b/sdk/src/types/generated/AdminTaxonomy.tsindex 09de704be9..d5c61e3ba2 100644--- a/sdk/src/types/generated/AdminTaxonomy.ts+++ b/sdk/src/types/generated/AdminTaxonomy.ts@@ -1,4 +1,4 @@-// Typelizer digest 9fe9377da634d26889b6d963f45b0995+// Typelizer digest 3c6adfa5d7c0c42875006ac74dccb7ee//// DO NOT MODIFY: This file was automatically generated by Typelizer.import type {StoreTaxon, AdminMetafield} from '@/types'@@ -9,6 +9,7 @@ type AdminTaxonomy = {position: number;created_at: string;updated_at: string;+ root_id: string | null;root?: StoreTaxon;taxons?: Array<StoreTaxon>;metafields?: Array<AdminMetafield>;diff --git a/sdk/src/types/generated/StoreTaxon.ts b/sdk/src/types/generated/StoreTaxon.tsindex 9548ed5ab7..4e2669954c 100644--- a/sdk/src/types/generated/StoreTaxon.ts+++ b/sdk/src/types/generated/StoreTaxon.ts@@ -1,4 +1,4 @@-// Typelizer digest 42bec2cbcbb4cab11988d60b8926ef13+// Typelizer digest d6c34d6ae2c930c16890d437668c28eb//// DO NOT MODIFY: This file was automatically generated by Typelizer.import type {StoreMetafield} from '@/types'@@ -8,8 +8,6 @@ type StoreTaxon = {name: string;permalink: string;position: number;- lft: number;- rgt: number;depth: number;meta_title: string | null;meta_description: string | null;@@ -28,6 +26,7 @@ type StoreTaxon = {is_leaf: boolean;parent?: StoreTaxon;children?: Array<StoreTaxon>;+ ancestors?: Array<StoreTaxon>;metafields?: Array<StoreMetafield>;}diff --git a/sdk/src/types/generated/StoreTaxonomy.ts b/sdk/src/types/generated/StoreTaxonomy.tsindex 1b6341e39f..75594755ff 100644--- a/sdk/src/types/generated/StoreTaxonomy.ts+++ b/sdk/src/types/generated/StoreTaxonomy.ts@@ -1,4 +1,4 @@-// Typelizer digest 3ec2c0b4de2fe47144ae42e9622f485d+// Typelizer digest 526678b91244ea6eeafc743e2349148e//// DO NOT MODIFY: This file was automatically generated by Typelizer.import type {StoreTaxon, StoreMetafield} from '@/types'@@ -9,6 +9,7 @@ type StoreTaxonomy = {position: number;created_at: string;updated_at: string;+ root_id: string | null;root?: StoreTaxon;taxons?: Array<StoreTaxon>;metafields?: Array<StoreMetafield>;diff --git a/sdk/src/types/index.ts b/sdk/src/types/index.tsindex 3f470b5b91..271c588de3 100644--- a/sdk/src/types/index.ts+++ b/sdk/src/types/index.ts@@ -57,6 +57,13 @@ export interface ProductListParams extends ListParams {'q[taxons_id_eq]'?: string;}+export interface TaxonListParams extends ListParams {+ 'q[taxonomy_id_eq]'?: string | number;+ 'q[parent_id_eq]'?: string | number;+ 'q[depth_eq]'?: number;+ 'q[name_cont]'?: string;+}+export interface OrderListParams extends ListParams {'q[state_eq]'?: string;'q[completed_at_gte]'?: string;