spree_api 5.6.1 → 6.0.0.beta1

data/lib/spree/api/openapi/schema_helper.rb

@@ -97,15 +97,6 @@ module Spree
               },
               required: %w[allow actions subjects has_conditions]
             },
-            MeResponse: {
-              type: :object,
-              description: 'Current admin user profile and serialized permissions',
-              properties: {
-                user: { '$ref' => '#/components/schemas/AdminUser' },
-                permissions: { type: :array, items: { '$ref' => '#/components/schemas/PermissionRule' } }
-              },
-              required: %w[user permissions]
-            },
             ImportSchemaField: {
               type: :object,
               description: 'A canonical column of an import type, including per-store custom field columns',
@@ -132,7 +123,13 @@ module Spree
                 code: { type: :string, description: 'Machine-readable warning code', example: 'line_item_removed' },
                 message: { type: :string, description: 'Human-readable warning message', example: 'Blue T-Shirt was removed because it was sold out' },
                 line_item_id: { type: :string, nullable: true, description: 'Prefixed line item ID (when applicable)', example: 'li_abc123' },
-                variant_id: { type: :string, nullable: true, description: 'Prefixed variant ID (when applicable)', example: 'variant_abc123' }
+                variant_id: { type: :string, nullable: true, description: 'Prefixed variant ID (when applicable)', example: 'variant_abc123' },
+                item_index: {
+                  type: :integer,
+                  nullable: true,
+                  description: 'Position in the submitted items array, for warnings raised while applying a batch of item changes',
+                  example: 1
+                }
               },
               required: %w[code message]
             },
@@ -215,6 +212,20 @@ module Spree
         def admin_schemas
           schemas = common_schemas
 
+          # Only here: it points at `AdminUser`, which no other branch
+          # publishes — the store has no such user and a seller's team member
+          # is `TeamMember`. Declared in the shared set it became an
+          # unresolvable `$ref` in both of their specs.
+          schemas[:MeResponse] = {
+            type: :object,
+            description: 'Current admin user profile and serialized permissions',
+            properties: {
+              user: { '$ref' => '#/components/schemas/AdminUser' },
+              permissions: { type: :array, items: { '$ref' => '#/components/schemas/PermissionRule' } }
+            },
+            required: %w[user permissions]
+          }
+
           # Override AuthResponse for admin: reference AdminUser, and drop refresh_token from the body
           # (admin sets the refresh token as an HttpOnly cookie, not in the JSON response).
           schemas[:AuthResponse] = {
@@ -235,6 +246,160 @@ module Spree
           schemas
         end
 
+        # Get all seller schemas (Typelizer + common).
+        #
+        # The seller branch has no API-key credential, so its AuthResponse is
+        # neither the store's nor the admin's: signing in returns the JWT, the
+        # team member who signed in, and the sellers they may act for — the
+        # panel cannot make another request until it has picked one.
+        def seller_schemas
+          schemas = common_schemas
+
+          schemas[:AuthResponse] = {
+            type: :object,
+            properties: {
+              token: { type: :string, description: 'JWT access token, `seller_api` audience' },
+              user: { '$ref' => '#/components/schemas/TeamMember' },
+              sellers: {
+                type: :array,
+                description: 'The sellers this user may act for. Pick one and send its `id` as `X-Spree-Seller-Id` on every subsequent request.',
+                items: { '$ref' => '#/components/schemas/SellerSummary' }
+              }
+            },
+            required: %w[token user sellers]
+          }
+
+          schemas.merge!(seller_common_schemas)
+
+          begin
+            schemas.merge!(typelizer_schemas(:seller))
+          rescue StandardError => e
+            Rails.logger.warn "Failed to load Typelizer seller schemas: #{e.message}"
+          end
+
+          schemas
+        end
+
+        # Hand-written shapes the seller branch answers with that no serializer
+        # produces — bespoke controller hashes rather than Alba output.
+        def seller_common_schemas
+          {
+            SellerSummary: {
+              type: :object,
+              description: 'A seller the signed-in user may act for',
+              properties: {
+                id: { type: :string, description: 'Prefixed seller ID — send as `X-Spree-Seller-Id`', example: 'sel_abc123' },
+                name: { type: :string, example: 'Acme Supplies' },
+                status: { type: :string, example: 'approved', description: 'Seller lifecycle status' }
+              },
+              required: %w[id name status]
+            },
+            SellerMeSummary: {
+              type: :object,
+              description: 'A seller the signed-in user may act for, as `/me` reports it — the login response carries the same fields without `slug`.',
+              properties: {
+                id: { type: :string, description: 'Prefixed seller ID — send as `X-Spree-Seller-Id`', example: 'sel_abc123' },
+                name: { type: :string, example: 'Acme Supplies' },
+                slug: { type: :string, example: 'acme-supplies' },
+                status: { type: :string, example: 'approved', description: 'Seller lifecycle status' }
+              },
+              required: %w[id name slug status]
+            },
+            SellerMeResponse: {
+              type: :object,
+              description: 'The signed-in user, the sellers they may act for, and what they may do on the selected one',
+              properties: {
+                user: { '$ref' => '#/components/schemas/TeamMember' },
+                sellers: { type: :array, items: { '$ref' => '#/components/schemas/SellerMeSummary' } },
+                permissions: { type: :array, items: { '$ref' => '#/components/schemas/PermissionRule' } },
+                permission_keys: {
+                  type: :array,
+                  items: { type: :string },
+                  description: 'Permission keys on the selected seller. Empty until `X-Spree-Seller-Id` names one — capability is per seller.',
+                  example: %w[read_products write_products]
+                }
+              },
+              required: %w[user sellers permissions permission_keys]
+            },
+            OnboardingProgress: {
+              type: :object,
+              description: <<~DESC,
+                How far along the checklist is — not how close to approval, since
+                optional requirements count towards it too.
+
+                Deliberately just the two counts. A percentage is arithmetic over
+                them, which a client can do and which would otherwise be a second
+                definition of the same fact.
+              DESC
+              properties: {
+                done: { type: :integer, example: 3 },
+                total: { type: :integer, example: 5 }
+              },
+              required: %w[done total]
+            },
+            SellerOnboardingResponse: {
+              type: :object,
+              description: "What the marketplace asks of this seller before it will admit them",
+              properties: {
+                status: { type: :string, example: 'onboarding', description: "The seller's lifecycle status" },
+                progress: { '$ref' => '#/components/schemas/OnboardingProgress' },
+                requirements: { type: :array, items: { '$ref' => '#/components/schemas/RequirementStatus' } }
+              },
+              required: %w[status progress requirements]
+            },
+            SellerCountry: {
+              type: :object,
+              description: "A country as the panel's address forms need it",
+              properties: {
+                iso: { type: :string, example: 'US' },
+                iso3: { type: :string, example: 'USA' },
+                name: { type: :string, example: 'United States' },
+                states_required: { type: :boolean, example: true },
+                zipcode_required: { type: :boolean, example: true },
+                states: {
+                  type: :array,
+                  items: {
+                    type: :object,
+                    properties: {
+                      abbr: { type: :string, example: 'CA' },
+                      name: { type: :string, example: 'California' }
+                    },
+                    required: %w[abbr name]
+                  }
+                }
+              },
+              required: %w[iso iso3 name]
+            },
+            DirectUploadResponse: {
+              type: :object,
+              description: 'A presigned upload target. PUT the file to `direct_upload.url` with the given headers, then send `signed_id` as the submission\'s `file`.',
+              properties: {
+                signed_id: { type: :string, description: 'Send this as a submission\'s `file`', example: 'eyJfcmFpbHMiOnsibWVzc2FnZSI6...' },
+                direct_upload: {
+                  type: :object,
+                  properties: {
+                    url: { type: :string, example: 'https://storage.example.com/uploads/abc123' },
+                    headers: { type: :object, additionalProperties: { type: :string } }
+                  },
+                  required: %w[url headers]
+                }
+              },
+              required: %w[signed_id direct_upload]
+            },
+            AuthProvidersResponse: {
+              type: :object,
+              description: 'Sign-in methods this marketplace offers sellers, for the login page',
+              properties: {
+                providers: {
+                  type: :array,
+                  items: { type: :object, additionalProperties: true }
+                }
+              },
+              required: %w[providers]
+            }
+          }
+        end
+
         private
 
         def typelizer_schemas(writer_name)
@@ -332,7 +497,7 @@ module Spree
           rule = schemas['PromotionRule'] || schemas[:PromotionRule]
           return unless rule
 
-          patch_id_arrays(rule, %w[product_ids category_ids customer_ids])
+          patch_id_arrays(rule, %w[product_ids category_ids customer_ids option_value_ids])
           patch_preference_schema(rule)
         end
 
@@ -419,13 +584,14 @@ module Spree
 
         # Typelizer adds nil to enum arrays for nullable fields.
         # OpenAPI 3.0 handles nullability via `nullable: true`, so the nil entry is redundant
-        # and causes issues with code generators.
+        # and causes issues with code generators. The array is often a model's
+        # frozen constant (`Spree::Fee::KINDS`), so it is replaced, never mutated.
         def strip_null_from_enums(schema)
           properties = schema[:properties] || {}
           properties.each_value do |prop|
             next unless prop.is_a?(Hash) && prop[:enum].is_a?(Array)
 
-            prop[:enum].reject!(&:nil?)
+            prop[:enum] = prop[:enum].compact
           end
         end
 

data/lib/spree/api/testing_support/v3/base.rb

@@ -34,7 +34,13 @@ shared_context 'API v3 Store' do
   let(:bearer_headers) { api_key_headers.merge('Authorization' => "Bearer #{jwt_token}") }
 
   before do
+    # Stubbed on both branch anchors, not just the shared base — the anchors
+    # define their own `current_store` (KeyStoreContext), which would shadow
+    # a stub installed on the base class. Specs stub methods on this exact
+    # `store` instance, so resolution must return it by identity.
     allow_any_instance_of(Spree::Api::V3::BaseController).to receive(:current_store).and_return(store)
+    allow_any_instance_of(Spree::Api::V3::Store::BaseController).to receive(:current_store).and_return(store)
+    allow_any_instance_of(Spree::Api::V3::Store::ResourceController).to receive(:current_store).and_return(store)
   end
 end
 
@@ -60,7 +66,11 @@ shared_context 'API v3 Admin' do
   let(:bearer_headers) { api_key_headers.merge('Authorization' => "Bearer #{admin_jwt_token}") }
 
   before do
+    # See the 'API v3 Store' context — the admin anchors define their own
+    # `current_store` (Admin::StoreContext), which shadows a base-class stub.
     allow_any_instance_of(Spree::Api::V3::BaseController).to receive(:current_store).and_return(store)
+    allow_any_instance_of(Spree::Api::V3::Admin::BaseController).to receive(:current_store).and_return(store)
+    allow_any_instance_of(Spree::Api::V3::Admin::ResourceController).to receive(:current_store).and_return(store)
   end
 end
 
@@ -70,23 +80,44 @@ shared_context 'API v3 Admin authenticated' do
   let(:headers) { bearer_headers }
 end
 
-# Authenticates as an admin whose ability is restricted to a single custom
-# permission set, so authorization specs can assert what a limited role can and
-# cannot do. Define `custom_permission_set` (a Spree::PermissionSets::Base
-# subclass) in the including example. The global permission registry is saved
-# and restored around each example so it doesn't leak into other specs.
-shared_context 'API v3 Admin with custom permissions' do
-  include_context 'API v3 Admin'
+# The marketplace seller panel. Deliberately no `current_seller` stub: the
+# header and the membership lookup behind it are what these specs exist to
+# exercise, so stubbing them would test nothing.
+shared_context 'API v3 Seller' do
+  let(:store) { @default_store || create(:store, default: true) }
+  let(:seller) { create(:seller, :approved, store: store) }
+  let(:seller_role) { create(:role, name: 'Seller', resource: seller, permissions: %w[write_products]) }
+  let(:seller_user) do
+    create(:admin_user, :without_admin_role).tap { |user| seller.add_user(user, seller_role) }
+  end
 
-  around do |example|
-    saved = Spree.permissions.dup
-    Spree.permissions.reset!
-    example.run
-  ensure
-    Spree.permissions.replace(saved)
+  let(:seller_jwt_token) do
+    Spree::Api::V3::TestingSupport.generate_jwt(
+      seller_user, audience: Spree::Api::V3::JwtAuthentication::JWT_AUDIENCE_SELLER
+    )
+  end
+  let(:seller_headers) do
+    { 'Authorization' => "Bearer #{seller_jwt_token}", 'X-Spree-Seller-Id' => seller.prefixed_id }
   end
+end
+
+shared_context 'API v3 Seller authenticated' do
+  include_context 'API v3 Seller'
+
+  let(:headers) { seller_headers }
+end
+
+# Authenticates as an admin whose ability is restricted to specific catalog
+# permission keys, so authorization specs can assert what a limited role can
+# and cannot do. Define `custom_permissions` (an array of catalog keys, e.g.
+# `%w[read_orders write_products]`) in the including example. Roles are data,
+# so nothing global is mutated.
+shared_context 'API v3 Admin with custom permissions' do
+  include_context 'API v3 Admin'
 
-  let(:custom_role) { create(:role, name: 'limited') }
+  let(:custom_permissions) { [] }
+  # A role belongs to what it governs, so it must be the store under test.
+  let(:custom_role) { create(:role, name: 'limited', permissions: custom_permissions, resource: store) }
   let(:custom_admin) { create(:admin_user, :without_admin_role) }
   let(:headers) do
     { 'Authorization' => "Bearer #{Spree::Api::V3::TestingSupport.generate_jwt(custom_admin, audience: Spree::Api::V3::JwtAuthentication::JWT_AUDIENCE_ADMIN)}" }
@@ -94,7 +125,6 @@ shared_context 'API v3 Admin with custom permissions' do
 
   before do
     custom_admin.spree_roles << custom_role
-    Spree.permissions.assign(:limited, custom_permission_set)
   end
 end
 

data/lib/spree/api.rb

@@ -4,6 +4,7 @@ require 'alba'
 require 'oj'
 require 'typelizer'
 require 'typelizer/proc_resource_resolution'
+require 'typelizer/open_enums'
 
 module Spree
   module Api
@@ -12,10 +13,10 @@ module Spree
   # API dependencies accessor for cleaner access to API dependencies
   #
   # @example Getting a dependency (returns resolved class)
-  #   Spree.api.storefront_coupon_handler.call(order: order, coupon_code: code)
+  #   Spree.api.product_serializer.render(product)
   #
   # @example Setting a dependency
-  #   Spree.api.storefront_coupon_handler = MyApp::CouponHandler
+  #   Spree.api.product_serializer = MyApp::ProductSerializer
   #
   # @return [Spree::ApiDependenciesAccessor] the API dependencies accessor
   def self.api
@@ -51,8 +52,13 @@ module Spree
     def api_dependency?(name)
       return false unless defined?(Spree::Api::Dependencies)
 
-      # Check both V3 and dynamically added V2 dependencies
-      Spree::Api::Dependencies.class::INJECTION_POINTS.include?(name)
+      dependencies = Spree::Api::Dependencies.class
+
+      # Check V3, dynamically added V2, and the pre-rename names that forward
+      # to their replacement for one release.
+      dependencies::INJECTION_POINTS.include?(name) ||
+        (dependencies.const_defined?(:LEGACY_SERIALIZER_KEYS) &&
+          dependencies::LEGACY_SERIALIZER_KEYS.key?(name))
     end
   end
 end

data/lib/typelizer/open_enums.rb

@@ -0,0 +1,35 @@
+module Typelizer
+  # A `typelize` entry with `enum:` alone is a closed list — the right shape
+  # for values nothing outside core can grow (units, match policies). Adding
+  # `enum_type_name:` marks the list as one an extension may extend
+  # (`has_status` values, `Spree::Fee::KINDS`), and both generated contracts
+  # follow suit: the TypeScript type becomes a named, exported union that stays
+  # open, and the OpenAPI property becomes an open enum, so a client generated
+  # from either still accepts an added value while every built-in value stays
+  # documented and autocompletable.
+  module OpenEnums
+    module Property
+      def enum_definition(...)
+        definition = super
+        definition && "#{definition} | (string & {})"
+      end
+    end
+
+    module Schema
+      OPEN_ENUM_DESCRIPTION = 'The values listed are the built-in ones; extensions may add more.'.freeze
+
+      def inline_schema(definition, property, openapi_version:)
+        return super unless property.enum_type_name && property.enum.is_a?(Array) && !property.multi
+
+        open = { anyOf: [{ type: :string, enum: property.enum.compact }, { type: :string }] }
+        apply_nullable(open, property, openapi_version: openapi_version)
+        apply_metadata(open, property)
+        open[:description] ||= OPEN_ENUM_DESCRIPTION
+        open
+      end
+    end
+  end
+end
+
+Typelizer::Property.prepend(Typelizer::OpenEnums::Property)
+Typelizer::OpenAPI.singleton_class.prepend(Typelizer::OpenEnums::Schema)