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.

Let a merchant pick where prices and stock come from

Damian Legawiec6fa44b07ae92
diff --git a/packages/admin-sdk/src/types/generated/Store.ts b/packages/admin-sdk/src/types/generated/Store.ts
index 696a0a95e1..d60959cc08 100644
--- a/packages/admin-sdk/src/types/generated/Store.ts
+++ b/packages/admin-sdk/src/types/generated/Store.ts
@@ -1,4 +1,4 @@
-// Typelizer digest d6a5f7e0d9f02e97d1533ffe2461437e
+// Typelizer digest cbba2cff141ec15159936d17716f76f6
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {SetupTask} from '@/types'
@@ -36,6 +36,10 @@ interface Store {
preferred_show_products_without_price: boolean;
preferred_disable_sku_validation: boolean;
preferred_order_routing_strategy: string;
+ preferred_pricing_provider: string;
+ preferred_inventory_provider: string;
+ preferred_pricing_provider_failure_policy: string;
+ preferred_inventory_provider_failure_policy: string;
preferred_document_number_format: string;
preferred_order_number_prefix: string;
preferred_order_number_suffix: string;
diff --git a/packages/dashboard/src/hooks/use-store-settings.ts b/packages/dashboard/src/hooks/use-store-settings.ts
index d2d4922c3e..cfa2f8aba5 100644
--- a/packages/dashboard/src/hooks/use-store-settings.ts
+++ b/packages/dashboard/src/hooks/use-store-settings.ts
@@ -16,6 +16,19 @@ export function useStoreSettings() {
})
}
+/**
+ * The pricing and inventory engines this store can choose between. Static for
+ * the life of a deploy — the list changes only when a connector gem is
+ * installed or an integration is connected — so it is cached generously.
+ */
+export function useStoreDataSources() {
+ return useQuery({
+ queryKey: useResourceKey(STORE_QUERY_RESOURCE, 'data-sources'),
+ queryFn: () => adminClient.store.dataSources(),
+ staleTime: 5 * 60 * 1000,
+ })
+}
+
export function useUpdateStoreSettings() {
return useResourceMutation<unknown, Error, StoreUpdateParams>({
mutationFn: (params) => adminClient.store.update(params),
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/settings/store.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/settings/store.tsx
index 2ec11bd14e..97a909a757 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/settings/store.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/settings/store.tsx
@@ -1,5 +1,5 @@
import { zodResolver } from '@hookform/resolvers/zod'
-import { SpreeError, type Store } from '@spree/admin-sdk'
+import { SpreeError, type Store, type StoreDataSourceProvider } from '@spree/admin-sdk'
import {
extensionFormValues,
extensionSubmitValues,
@@ -36,7 +36,7 @@ import {
useFormSubmitShortcut,
} from '@spree/dashboard-ui'
import { createFileRoute } from '@tanstack/react-router'
-import { useEffect, useMemo } from 'react'
+import { useCallback, useEffect, useMemo } from 'react'
import {
type Control,
Controller,
@@ -47,11 +47,17 @@ import {
} from 'react-hook-form'
import { useTranslation } from 'react-i18next'
import { ChoiceCardPicker } from '../../../../components/spree/choice-card-picker'
-import { useStoreSettings, useUpdateStoreSettings } from '../../../../hooks/use-store-settings'
+import {
+ useStoreDataSources,
+ useStoreSettings,
+ useUpdateStoreSettings,
+} from '../../../../hooks/use-store-settings'
import { getAvailableUiLocales } from '../../../../i18n-setup'
import {
CAPTURE_METHODS,
DOCUMENT_NUMBER_FORMATS,
+ INTERNAL_PROVIDER_KEY,
+ PROVIDER_FAILURE_POLICIES,
STOREFRONT_ACCESS_LEVELS,
type StoreSettingsFormValues,
storeSettingsFormSchema,
@@ -101,6 +107,14 @@ function storeToFormValues(store: Store): StoreSettingsFormValues {
preferred_address_requires_phone: store.preferred_address_requires_phone ?? false,
preferred_capture_method:
(store.preferred_capture_method as (typeof CAPTURE_METHODS)[number]) ?? 'checkout',
+ preferred_pricing_provider: store.preferred_pricing_provider || INTERNAL_PROVIDER_KEY,
+ preferred_inventory_provider: store.preferred_inventory_provider || INTERNAL_PROVIDER_KEY,
+ preferred_pricing_provider_failure_policy:
+ (store.preferred_pricing_provider_failure_policy as (typeof PROVIDER_FAILURE_POLICIES)[number]) ??
+ 'strict',
+ preferred_inventory_provider_failure_policy:
+ (store.preferred_inventory_provider_failure_policy as (typeof PROVIDER_FAILURE_POLICIES)[number]) ??
+ 'fallback',
preferred_tax_using_ship_address: store.preferred_tax_using_ship_address ?? true,
preferred_track_inventory_levels: store.preferred_track_inventory_levels ?? true,
preferred_stock_reservations_enabled: store.preferred_stock_reservations_enabled ?? true,
@@ -154,6 +168,14 @@ function StoreSettingsForm({ store }: { store: Store }) {
const { storeId } = useStore()
const updateMutation = useUpdateStoreSettings()
const switchAdminLocale = useSwitchAdminLocale()
+ const { data: dataSources } = useStoreDataSources()
+
+ // The card stays hidden until a connector gem is installed: a store with
+ // only Spree's own engines has nothing to choose between, and a select with
+ // one option is noise on a settings page.
+ const hasExternalDataSources =
+ (dataSources?.pricing_providers.length ?? 0) + (dataSources?.inventory_providers.length ?? 0) >
+ 2
const form = useForm<StoreSettingsFormValues>({
// eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -217,6 +239,11 @@ function StoreSettingsForm({ store }: { store: Store }) {
preferred_company_field_enabled: values.preferred_company_field_enabled,
preferred_address_requires_phone: values.preferred_address_requires_phone,
preferred_capture_method: values.preferred_capture_method,
+ preferred_pricing_provider: values.preferred_pricing_provider,
+ preferred_inventory_provider: values.preferred_inventory_provider,
+ preferred_pricing_provider_failure_policy: values.preferred_pricing_provider_failure_policy,
+ preferred_inventory_provider_failure_policy:
+ values.preferred_inventory_provider_failure_policy,
preferred_tax_using_ship_address: values.preferred_tax_using_ship_address,
preferred_track_inventory_levels: values.preferred_track_inventory_levels,
preferred_stock_reservations_enabled: values.preferred_stock_reservations_enabled,
@@ -295,6 +322,32 @@ function StoreSettingsForm({ store }: { store: Store }) {
})),
[t],
)
+ // A provider whose integration is not connected stays in the list but is
+ // not selectable — hiding it would leave a merchant wondering where the ERP
+ // they just installed went.
+ const providerOptions = useCallback(
+ (providers: StoreDataSourceProvider[] | undefined) =>
+ (providers ?? []).map((provider) => ({
+ value: provider.key,
+ label:
+ provider.key === INTERNAL_PROVIDER_KEY
+ ? t('admin.fields.store.data_sources.internal')
+ : provider.name,
+ disabled: !provider.available,
+ description: provider.available
+ ? undefined
+ : t('admin.fields.store.data_sources.not_connected'),
+ })),
+ [t],
+ )
+ const failurePolicyOptions = useMemo(
+ () =>
+ PROVIDER_FAILURE_POLICIES.map((value) => ({
+ value,
+ label: t(`admin.fields.store.data_sources.policies.${value}.label`),
+ })),
+ [t],
+ )
const captureMethodOptions = useMemo(
() =>
CAPTURE_METHODS.map((value) => ({
@@ -650,6 +703,49 @@ function StoreSettingsForm({ store }: { store: Store }) {
</FieldGroup>
</CardContent>
</Card>
+ {hasExternalDataSources && (
+ <Card>
+ <CardHeader>
+ <CardTitle>{t('admin.pages.settings.store.tab_data_sources')}</CardTitle>
+ </CardHeader>
+ <CardContent>
+ <FieldGroup>
+ <SelectField
+ id="store-pricing-provider"
+ label={t('admin.fields.store.data_sources.pricing_provider.label')}
+ help={t('admin.fields.store.data_sources.pricing_provider.help')}
+ name="preferred_pricing_provider"
+ control={form.control}
+ options={providerOptions(dataSources?.pricing_providers)}
+ />
+ <SelectField
+ id="store-pricing-failure-policy"
+ label={t('admin.fields.store.data_sources.pricing_failure_policy.label')}
+ help={t('admin.fields.store.data_sources.pricing_failure_policy.help')}
+ name="preferred_pricing_provider_failure_policy"
+ control={form.control}
+ options={failurePolicyOptions}
+ />
+ <SelectField
+ id="store-inventory-provider"
+ label={t('admin.fields.store.data_sources.inventory_provider.label')}
+ help={t('admin.fields.store.data_sources.inventory_provider.help')}
+ name="preferred_inventory_provider"
+ control={form.control}
+ options={providerOptions(dataSources?.inventory_providers)}
+ />
+ <SelectField
+ id="store-inventory-failure-policy"
+ label={t('admin.fields.store.data_sources.inventory_failure_policy.label')}
+ help={t('admin.fields.store.data_sources.inventory_failure_policy.help')}
+ name="preferred_inventory_provider_failure_policy"
+ control={form.control}
+ options={failurePolicyOptions}
+ />
+ </FieldGroup>
+ </CardContent>
+ </Card>
+ )}
<Card>
<CardHeader>
<CardTitle>{t('admin.pages.settings.store.tab_catalog')}</CardTitle>
diff --git a/packages/dashboard/src/schemas/store.ts b/packages/dashboard/src/schemas/store.ts
index 3653e7d2de..7776ff39d8 100644
--- a/packages/dashboard/src/schemas/store.ts
+++ b/packages/dashboard/src/schemas/store.ts
@@ -34,6 +34,10 @@ const NUMBER_AFFIX_PATTERN = /^[A-Z0-9#-]*$/
// concrete value. Labels live in `en.json` under
// `admin.fields.store.capture_method.options.*`.
export const CAPTURE_METHODS = ['checkout', 'on_dispatch', 'manual'] as const
+/** What a store does when its pricing or inventory provider cannot answer. */
+export const PROVIDER_FAILURE_POLICIES = ['strict', 'fallback'] as const
+/** Spree's own catalog and stock records — the default for both providers. */
+export const INTERNAL_PROVIDER_KEY = 'internal'
export const storeSettingsFormSchema = z.object({
name: z.string().min(1, { error: requiredMessage('store.name') }),
@@ -50,6 +54,10 @@ export const storeSettingsFormSchema = z.object({
preferred_company_field_enabled: z.boolean(),
preferred_address_requires_phone: z.boolean(),
preferred_capture_method: z.enum(CAPTURE_METHODS),
+ preferred_pricing_provider: z.string(),
+ preferred_inventory_provider: z.string(),
+ preferred_pricing_provider_failure_policy: z.enum(PROVIDER_FAILURE_POLICIES),
+ preferred_inventory_provider_failure_policy: z.enum(PROVIDER_FAILURE_POLICIES),
preferred_tax_using_ship_address: z.boolean(),
preferred_track_inventory_levels: z.boolean(),
preferred_stock_reservations_enabled: z.boolean(),
diff --git a/spree/api/app/controllers/spree/api/v3/admin/store_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/store_controller.rb
index 9e5d9550a7..8de025fb57 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/store_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/store_controller.rb
@@ -31,8 +31,38 @@ module Spree
end
end
+ # GET /api/v3/admin/store/data_sources
+ #
+ # The pricing and inventory engines this store can choose between,
+ # with whether each is usable — a provider whose integration is not
+ # connected is listed but not selectable, so the dashboard can say
+ # why rather than hiding it.
+ def data_sources
+ authorize! :show, current_store
+
+ render json: {
+ data: {
+ pricing_providers: describe(Spree.pricing_providers),
+ inventory_providers: describe(Spree.inventory_providers),
+ failure_policies: Spree::ProviderFailurePolicy::VALUES
+ }
+ }
+ end
+
private
+ def describe(provider_classes)
+ provider_classes.map do |provider_class|
+ {
+ key: provider_class.key,
+ name: provider_class.provider_name,
+ integration_class: provider_class.integration_class,
+ integration_type: provider_class.integration_class.presence&.safe_constantize&.api_type,
+ available: provider_class.available_for_store?(current_store)
+ }
+ end
+ end
+
def serialize_store
serializer_class.new(current_store, params: serializer_params).to_h
end
@@ -70,6 +100,10 @@ module Spree
:preferred_show_products_without_price,
:preferred_disable_sku_validation,
:preferred_order_routing_strategy,
+ :preferred_pricing_provider,
+ :preferred_inventory_provider,
+ :preferred_pricing_provider_failure_policy,
+ :preferred_inventory_provider_failure_policy,
:preferred_document_number_format,
:preferred_order_number_prefix,
:preferred_order_number_suffix,
diff --git a/spree/api/app/serializers/spree/api/v3/admin/store_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/store_serializer.rb
index 71588ae061..913d378f40 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/store_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/store_serializer.rb
@@ -36,6 +36,10 @@ module Spree
preferred_show_products_without_price: :boolean,
preferred_disable_sku_validation: :boolean,
preferred_order_routing_strategy: :string,
+ preferred_pricing_provider: :string,
+ preferred_inventory_provider: :string,
+ preferred_pricing_provider_failure_policy: :string,
+ preferred_inventory_provider_failure_policy: :string,
preferred_document_number_format: :string,
preferred_order_number_prefix: :string,
preferred_order_number_suffix: :string,
@@ -74,6 +78,10 @@ module Spree
:preferred_show_products_without_price,
:preferred_disable_sku_validation,
:preferred_order_routing_strategy,
+ :preferred_pricing_provider,
+ :preferred_inventory_provider,
+ :preferred_pricing_provider_failure_policy,
+ :preferred_inventory_provider_failure_policy,
:preferred_document_number_format,
:preferred_order_number_prefix,
:preferred_order_number_suffix,
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/store_data_sources_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/store_data_sources_spec.rb
new file mode 100644
index 0000000000..83235f70fb
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/admin/store_data_sources_spec.rb
@@ -0,0 +1,67 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Admin::StoreController, 'data sources', type: :controller do
+ render_views
+
+ include_context 'API v3 Admin authenticated'
+
+ before { request.headers.merge!(headers) }
+
+ describe 'GET #data_sources' do
+ it 'lists Spree own engines as available' do
+ get :data_sources, as: :json
+
+ expect(response).to have_http_status(:ok)
+ pricing = json_response['data']['pricing_providers']
+ expect(pricing.map { |row| row['key'] }).to include('internal')
+ expect(pricing.find { |row| row['key'] == 'internal' }['available']).to be(true)
+ end
+
+ it 'offers the failure policies a merchant can choose between' do
+ get :data_sources, as: :json
+
+ expect(json_response['data']['failure_policies']).to contain_exactly('fallback', 'strict')
+ end
+
+ # A connector gem's provider is listed but not selectable until its
+ # integration is connected, so the dashboard can say why rather than
+ # leaving the merchant wondering where their ERP went.
+ it 'marks a provider whose integration is not connected as unavailable' do
+ needs_credentials = Class.new(Spree::PricingProvider::Base) do
+ def self.key = 'acme_erp'
+ def self.provider_name = 'Acme ERP'
+ def self.integration_class = 'SpreeAcmeErp::Integration'
+ end
+ Spree.pricing_providers << needs_credentials
+
+ get :data_sources, as: :json
+
+ row = json_response['data']['pricing_providers'].find { |item| item['key'] == 'acme_erp' }
+ expect(row['available']).to be(false)
+ expect(row['integration_class']).to eq('SpreeAcmeErp::Integration')
+ ensure
+ Spree.pricing_providers.delete(needs_credentials)
+ end
+ end
+
+ describe 'PATCH #update' do
+ it 'saves the chosen providers and policies' do
+ patch :update, params: {
+ preferred_pricing_provider: 'internal',
+ preferred_inventory_provider: 'internal',
+ preferred_pricing_provider_failure_policy: 'fallback',
+ preferred_inventory_provider_failure_policy: 'strict'
+ }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['preferred_pricing_provider_failure_policy']).to eq('fallback')
+ expect(store.reload.preferred_inventory_provider_failure_policy).to eq('strict')
+ end
+
+ it 'refuses a policy that is neither falling back nor strict' do
+ patch :update, params: { preferred_pricing_provider_failure_policy: 'ignore' }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+end
diff --git a/spree/core/spec/models/concerns/spree/store_data_sources_spec.rb b/spree/core/spec/models/concerns/spree/store_data_sources_spec.rb
new file mode 100644
index 0000000000..18be60d04b
--- /dev/null
+++ b/spree/core/spec/models/concerns/spree/store_data_sources_spec.rb
@@ -0,0 +1,99 @@
+require 'spec_helper'
+
+RSpec.describe Spree::StoreDataSources do
+ let(:store) { create(:store) }
+
+ describe 'defaults' do
+ it 'uses Spree own catalog and stock records' do
+ expect(store.pricing_provider_instance).to be_a(Spree::PricingProvider::Internal)
+ expect(store.inventory_provider_instance).to be_a(Spree::InventoryProvider::Internal)
+ expect(store).to be_internal_pricing
+ expect(store).to be_internal_inventory
+ end
+
+ # The asymmetry is the point: selling stock that turns out not to exist is
+ # recoverable, charging the wrong price is a dispute.
+ it 'refuses to price without its provider but will sell on a stale stock figure' do
+ expect(store.pricing_failure_policy).to eq('strict')
+ expect(store.inventory_failure_policy).to eq('fallback')
+ end
+ end
+
+ describe 'validation' do
+ it 'rejects a failure policy that is neither falling back nor strict' do
+ store.preferred_pricing_provider_failure_policy = 'ignore'
+
+ expect(store).not_to be_valid
+ expect(store.errors[:preferred_pricing_provider_failure_policy]).to be_present
+ end
+
+ it 'accepts both known policies' do
+ Spree::ProviderFailurePolicy::VALUES.each do |policy|
+ store.preferred_inventory_provider_failure_policy = policy
+
+ expect(store).to be_valid
+ end
+ end
+ end
+
+ describe 'selection' do
+ let(:provider_class) do
+ Class.new(Spree::PricingProvider::Base) do
+ def self.key = 'contract'
+ def price_for(_context) = nil
+ end
+ end
+
+ before { Spree.pricing_providers << provider_class }
+ after { Spree.pricing_providers.delete(provider_class) }
+
+ it 'resolves a registered provider by its key' do
+ stub_store_preferences(store, pricing_provider: 'contract')
+
+ expect(store.pricing_provider_instance).to be_a(provider_class)
+ expect(store).not_to be_internal_pricing
+ end
+
+ # A store object outlives the setting: a merchant switching provider, or a
+ # job holding one for hours, must not keep getting the old answer.
+ it 'follows a preference change rather than answering from a stale instance' do
+ store.update!(preferred_pricing_provider: 'contract')
+ expect(store.pricing_provider_instance).to be_a(provider_class)
+
+ store.update!(preferred_pricing_provider: 'internal')
+
+ expect(store.pricing_provider_instance).to be_a(Spree::PricingProvider::Internal)
+ end
+
+ # A gem removed from the Gemfile must not take pricing down with it.
+ it 'falls back to internal when the key names a provider that is gone' do
+ stub_store_preferences(store, pricing_provider: 'removed_gem')
+
+ expect(store.pricing_provider_instance).to be_a(Spree::PricingProvider::Internal)
+ end
+ end
+
+ describe 'availability for a store' do
+ let(:integration_provider) do
+ Class.new(Spree::PricingProvider::Base) do
+ def self.key = 'needs_credentials'
+ def self.integration_class = 'SpreeTest::Integration'
+ end
+ end
+
+ it 'is unavailable until its integration is connected' do
+ expect(integration_provider.available_for_store?(store)).to be(false)
+ end
+
+ it 'needs no integration when it declares none' do
+ expect(Spree::PricingProvider::Internal.available_for_store?(store)).to be(true)
+ end
+ end
+
+ describe 'registry keys' do
+ it 'names the internal providers by the key the preference stores' do
+ expect(Spree::PricingProvider::Internal.key).to eq('internal')
+ expect(Spree::InventoryProvider::Internal.key).to eq('internal')
+ end
+ end
+end