spree_core 6.0.0.rc2 → 6.0.0.rc4

data/app/models/spree/tax_rate.rb

@@ -9,6 +9,10 @@ module Spree
     # zone_id any more, but the column stays in the database through 6.0: it is
     # what `spree:migrate_tax_zones` converts from, and that task runs after
     # db:migrate. The physical drop lands in 6.1.
+    #
+    # The same goes for included_in_price: whether tax sits inside a price is
+    # the market's choice (Spree::Market#tax_inclusive), and the column is read
+    # only by `spree:markets:backfill_tax_inclusive`, which clears it.
 
     acts_as_paranoid
 
@@ -52,15 +56,10 @@ module Spree
     }
     # The same question asked with an address in hand.
     scope :for_address, ->(address) { for_jurisdiction(address&.country_code, address&.state_code) }
-    # Country-wide: unlike for_jurisdiction(country_code, nil) this leaves the
-    # state unconstrained, so it sums a country's state-level rates too. Used
-    # where the state is irrelevant — backing VAT out of a gross price.
-    scope :for_country, ->(country_code) { where(country_code: [country_code.presence, nil].uniq) }
     scope :for_tax_category,
           ->(category) { where(tax_category_id: category.try(:id)) }
-    scope :included_in_price, -> { where(included_in_price: true) }
 
-    self.whitelisted_ransackable_attributes = %w[amount rate country_code state_code tax_category_id included_in_price name]
+    self.whitelisted_ransackable_attributes = %w[amount rate country_code state_code tax_category_id name]
     ransack_alias :rate, :amount
     search_by :name
 
@@ -92,38 +91,13 @@ module Spree
       self.rate_percent = value
     end
 
-    # The included-in-price rate to back out of a gross price.
-    #
-    # @param options [Hash] +:country+ (or +:address+) and +:tax_category+
-    # @return [BigDecimal] 0 when the jurisdiction or category is unknown
-    def self.included_tax_amount_for(options)
-      # +:country+ is a documented override point and the VAT path still hands
-      # it a Spree::Country, so take the code off whichever arrives.
-      country = options[:country]
-      country_code = country.try(:iso) || country.presence || options[:address]&.country_code
-      return 0 unless country_code && options[:tax_category]
-
-      scope = options[:address] ? for_address(options[:address]) : for_country(country_code)
-      # Per-store tax configuration is the norm since 6.0, so without this the
-      # sum would add up every store's rate for the same country.
-      store = options[:store] || Spree::Current.store
-      scope = scope.for_store(store) if store
-      scope.included_in_price.for_tax_category(options[:tax_category]).sum(:amount)
-    end
-
-    def included?
-      included_in_price
-    end
-
-    def additional?
-      !included_in_price
-    end
-
     # The customer-facing label snapshotted onto TaxLine rows.
     #
+    # @param included [Boolean] whether the tax sits inside the price, which
+    #   the sale's market decides (Spree::Market#tax_inclusive)
     # @return [String]
-    def adjustment_label
-      I18n.t "spree.adjustment_labels.tax_rates.#{included_in_price? ? :including_tax : :excluding_tax}",
+    def adjustment_label(included: false)
+      I18n.t "spree.adjustment_labels.tax_rates.#{included ? :including_tax : :excluding_tax}",
               name: name.presence || tax_category.name,
               amount: amount_for_label
     end

data/app/models/spree/translations/batch.rb

@@ -45,12 +45,22 @@ module Spree
         @records = []
       end
 
-      # Distinct +write_<resource>+ scopes a caller needs to authorize this
-      # batch — one per resource type present. Lets the API layer gate an
-      # API-key request without re-deriving scope names.
+      # Distinct write permissions a caller needs to authorize this batch —
+      # one per resource type present.
+      #
+      # Each resource names its own, because several are guarded by a
+      # permission not named after them: an option type rides
+      # `write_products`, a policy rides `write_settings`. Deriving the name
+      # from the type produced strings outside the permission catalog, which
+      # no credential could hold and which the API therefore skipped — so a
+      # grant narrowed to reading could still rewrite a store's policy text.
+      #
+      # A type that resolves to nothing is left out; `resolve_record!` is what
+      # reports it, one entry at a time with its index.
+      #
       # @return [Array<String>]
       def required_scopes
-        @entries.map { |entry| "write_#{entry[:resource_type].to_s.pluralize}" }.uniq
+        @entries.filter_map { |entry| resource_class(entry[:resource_type])&.translation_write_permission }.uniq
       end
 
       # Upserts every entry in one transaction. Yields each resolved record

data/app/services/spree/carts/price_items.rb

@@ -71,20 +71,14 @@ module Spree
         resolutions = Array(resolutions)
         return if resolutions.empty?
 
-        # One derivation for the batch: every line in a resolution set belongs
-        # to the same cart, and tax_address / tax_country walk associations and
-        # a store preference that would otherwise be re-read per line.
-        owner = resolutions.first.first.owner
-        vat_inputs = { address: owner&.tax_address, country: owner&.tax_country, market: owner&.market }
-
         resolutions.each do |line_item, price|
           # Probe-based flows resolve against stand-ins, so the guard has to
           # hold at the write too.
           next if line_item.manual_price?
 
-          amount = price.price_including_vat_for(**vat_inputs)
+          amount = price.price
           # Marked before the blank guard: the provider has already answered,
-          # so a restatement that comes back blank must still not send the
+          # so a price that comes back blank must still not send the
           # after_save callback back to the provider from inside the caller's
           # transaction. Only the assign-for-a-coming-save case needs it — a
           # persisted write goes through update_columns and fires no callbacks.

data/app/services/spree/carts/split_by_seller.rb

@@ -34,10 +34,15 @@ module Spree
       # recorded about the purchase (copied from the cart), so every child gets
       # the same hash — and so does the group. Once split, each order's
       # metadata is its own: edits never propagate between siblings.
+      #
+      # `applied_tax_exemptions` rides along, or a sibling resolves again and
+      # takes override ids that match nothing it owns. Line items keep their ids
+      # here; a divided fulfillment and its money rows do not, so an override
+      # naming one is stale — latent while nothing supplies overrides.
       CARRIED_TO_SIBLING = %w[
         email currency locale market_id channel_id company_id
         customer_id token accept_marketing preferred_stock_location_id
-        customer_note last_ip_address po_number metadata
+        customer_note last_ip_address po_number metadata applied_tax_exemptions
       ].freeze
 
       # @param order [Spree::Order] the paid draft order, adopted as the

data/app/services/spree/carts/update.rb

@@ -28,10 +28,11 @@ module Spree
         success(cart)
       rescue ActiveRecord::RecordNotFound
         raise
-      rescue Spree::Pricing::PriceResolution::ProviderUnavailable => e
-        # A strict store could not confirm a price. The transaction has rolled
-        # back, so the address change is not committed either — better than
-        # saving a destination whose prices nobody stood behind.
+      rescue Spree::Pricing::PriceResolution::ProviderUnavailable, Spree::Tax::ProviderError => e
+        # A strict store could not confirm a price, or the tax engine did not
+        # produce tax. The transaction has rolled back, so the address change is
+        # not committed either — better than saving a destination whose prices
+        # or tax nobody stood behind.
         #
         # The in-memory cart still holds the rolled-back attributes, though, so
         # a caller that renders the object it passed in would show the customer
@@ -48,7 +49,7 @@ module Spree
         end
         cart.warnings |= warnings if warnings.present?
 
-        failure(cart, I18n.t('spree.cart_line_item.pricing_unavailable'))
+        failure(cart, { code: unavailable_code_for(e), message: unavailable_message_for(e) })
       rescue ActiveRecord::RecordInvalid => e
         failure(cart, e.record.errors.full_messages.to_sentence)
       rescue StandardError => e
@@ -229,6 +230,29 @@ module Spree
         end
       end
 
+      # Three ways an external service can leave a sale unpriced, and a
+      # customer can only act on what they are told. A refused calculation
+      # carries the engine's own words, because "the postcode is not valid for
+      # that state" is something they can fix and "please try again" is not.
+      # The same split the API's own handler makes: a refusal names something
+      # to fix, an outage is worth retrying, and a price that could not be
+      # confirmed is neither tax case.
+      def unavailable_code_for(error)
+        case error
+        when Spree::Tax::CalculationRefused then 'tax_calculation_refused'
+        when Spree::Tax::ProviderError then 'tax_provider_unavailable'
+        else 'provider_unavailable'
+        end
+      end
+
+      def unavailable_message_for(error)
+        case error
+        when Spree::Tax::CalculationRefused then error.message.to_s
+        when Spree::Tax::ProviderError then I18n.t('spree.cart_line_item.tax_unavailable')
+        else I18n.t('spree.cart_line_item.pricing_unavailable')
+        end
+      end
+
       # Three-way dispatch on the cart→checkout transition:
       # entering checkout → Reserve, mid-checkout mutation → Extend, reverting to cart → Release.
       # A failed Reserve raises so the enclosing transaction rolls back and the
@@ -256,10 +280,13 @@ module Spree
         else
           cart.recalculate_totals!
         end
-      rescue Spree::Pricing::PriceResolution::ProviderUnavailable
+      rescue Spree::Pricing::PriceResolution::ProviderUnavailable, Spree::Tax::ProviderError
         # Deliberately not swallowed like the rest: a strict store refusing to
         # price must roll the whole update back, so `call` sees it and the
-        # address change does not commit around unconfirmed prices.
+        # address change does not commit around unconfirmed prices. A tax engine
+        # that cannot answer is the same problem one column over — swallowing it
+        # showed the customer a total with tax missing and saved the address
+        # anyway, so the mistake only surfaced when they tried to pay.
         raise
       rescue StandardError => e
         Rails.error.report(e, context: { order_id: cart.id }, source: 'spree.checkout')

data/app/services/spree/email_templates/preview.rb

@@ -23,8 +23,11 @@ module Spree
       # @param email_key [String, nil] for the layout or a partial, the email to show it in
       # @param strict [Boolean] whether an unknown variable raises
       # @param branding [Hash] unsaved branding values (see Spree::Emails::Branding)
+      # @param mailer_logo_signed_id [String, nil] the signed id of an unsaved, uploaded email logo
+      # @param mailer_logo_cleared [Boolean] whether the email logo is previewed as removed
       def initialize(store:, key:, locale: Spree::EmailTemplate::ANY_LOCALE, subject: nil, body: nil,
-                     record_id: nil, email_key: nil, strict: false, branding: {})
+                     record_id: nil, email_key: nil, strict: false, branding: {}, mailer_logo_signed_id: nil,
+                     mailer_logo_cleared: false)
         @store = store
         @key = key
         @locale = locale.presence || Spree::EmailTemplate::ANY_LOCALE
@@ -34,16 +37,20 @@ module Spree
         @email_key = email_key
         @strict = strict
         @branding = branding
+        @mailer_logo_signed_id = mailer_logo_signed_id
+        @mailer_logo_cleared = mailer_logo_cleared
       end
 
       # @return [Spree::Emails::RenderedEmail]
       # @raise [Spree::EmailTemplates::NoSampleRecord] when the store has no record to build the sample from
+      # @raise [ActiveRecord::RecordInvalid] when the unsaved logo is one saving the store would refuse
+      # @raise [ActiveSupport::MessageVerifier::InvalidSignature] when the unsaved logo's signed id is not valid
       def call
         sample = email.sample_class.new(store: @store, record_id: @record_id)
 
         in_locale do
-          renderer = Spree::Emails::Renderer.new(resolver: resolver, store: @store, currency: sample.currency, strict: @strict,
-                                                 branding: @branding)
+          renderer = Spree::Emails::Renderer.new(resolver: resolver, store: email_store, currency: sample.currency,
+                                                 strict: @strict, branding: @branding)
           sample_variables = sample.variables
           @variables = renderer.variables(sample_variables)
           @rendered = renderer.render(resolver.find(email.key), sample_variables)
@@ -66,6 +73,20 @@ module Spree
         Spree.editable_email_templates[@key] || raise(ArgumentError, "#{@key} is not an editable email template")
       end
 
+      # The store as the email shows it. An unsaved logo upload or removal is
+      # applied to a copy that is never saved, and checked as saving the store
+      # checks it, so the preview never shows a logo the Save button refuses.
+      def email_store
+        return @store if @mailer_logo_signed_id.nil? && !@mailer_logo_cleared
+
+        @email_store ||= @store.class.find(@store.id).tap do |store|
+          store.mailer_logo = @mailer_logo_cleared ? nil : @mailer_logo_signed_id
+          store.validate
+          (store.errors.attribute_names - [:mailer_logo]).each { |attribute| store.errors.delete(attribute) }
+          raise ActiveRecord::RecordInvalid, store if store.errors.any?
+        end
+      end
+
       def resolver
         @resolver ||= Spree::Emails::TemplateResolver.for_mailers(store: @store, locale: language, drafts: drafts)
       end

data/app/services/spree/seeds/store_resources.rb

@@ -18,6 +18,7 @@ module Spree
         Spree::Events.disable do
           ActiveRecord::Base.no_touching do
             TaxCategories.call(store: store)
+            TaxExemptionReasons.call(store: store)
             Channels.call(store: store)
             Roles.call(store: store)
             DigitalDelivery.call(store: store)

data/app/services/spree/seeds/tax_exemption_reasons.rb

@@ -0,0 +1,28 @@
+module Spree
+  module Seeds
+    # The reasons a business can give for buying without tax. Neutral codes
+    # that Spree's own engine keeps for reference; a store using an engine
+    # that reads them (Avalara) changes each code to that engine's.
+    class TaxExemptionReasons
+      prepend Spree::ServiceModule::Base
+      include StoreScoped
+
+      REASONS = {
+        'RESALE' => 'Resale',
+        'GOVERNMENT' => 'Government',
+        'CHARITABLE' => 'Charitable organization',
+        'EDUCATIONAL' => 'Educational institution',
+        'MANUFACTURING' => 'Manufacturing',
+        'AGRICULTURAL' => 'Agricultural'
+      }.freeze
+
+      private
+
+      def seed(store)
+        REASONS.each do |code, name|
+          store.tax_exemption_reasons.find_or_create_by_code_or_name!(code: code, name: name)
+        end
+      end
+    end
+  end
+end

data/app/services/spree/tax/resolve_exemptions.rb

@@ -29,9 +29,18 @@ module Spree
         return success([]) if company.nil? || address.nil?
 
         success(
-          company.tax_exemption_certificates.active.for_address(address).map do |certificate|
+          company.tax_exemption_certificates.active.for_address(address).includes(:tax_exemption_reason).filter_map do |certificate|
+            reason = certificate.tax_exemption_reason
+            # A certificate recorded before reasons existed keeps its old code
+            # until `spree:upgrade:tax_exemption_reasons` links it. One with
+            # neither (its reason row removed outside the app) is skipped
+            # rather than failing tax for every order of the company.
+            reason_code = reason&.code || certificate.reason_code
+            next if reason_code.blank?
+
             Spree::TaxExemption.new(
-              reason_code: certificate.reason_code,
+              reason_code: reason_code,
+              reason_name: reason&.name,
               certificate_number: certificate.certificate_number,
               country_code: certificate.country_code,
               state_code: certificate.state_code

data/app/services/spree/update_check.rb

@@ -34,9 +34,16 @@ module Spree
     LARGEST_BUCKET = '100k+'.freeze
 
     class << self
+      # Always false in the test environment and on CI servers (which set
+      # +CI+), so no test run ever reaches spreecloud.io; specs stub the
+      # request instead.
+      #
       # @return [Boolean] false when the operator turned the check off
       def enabled?
-        Spree::Config.update_check_enabled && !env_flag?('SPREE_UPDATE_CHECK_DISABLED')
+        !Rails.env.test? &&
+          !env_flag?('CI') &&
+          Spree::Config.update_check_enabled &&
+          !env_flag?('SPREE_UPDATE_CHECK_DISABLED')
       end
 
       # When false, the check still runs but sends the running version only.

data/app/tools/spree/agent_tools/create_export.rb

@@ -0,0 +1,116 @@
+module Spree
+  module AgentTools
+    # Exports records to a CSV the merchant can download.
+    #
+    # Mutating not because it changes the store — it does not — but because
+    # it produces a file of store data and emails a link to it. That leaves
+    # the building, so a merchant decides, not the model.
+    class CreateExport < Spree::AgentTool
+      tool_name 'create_export'
+      description 'Export records to a CSV file. Say which kind of records and, ' \
+                  'optionally, the same filters search_resources accepts. The merchant ' \
+                  'approves before the file is generated.'
+      # Exports are gated on the READ scope of what is being exported — the
+      # Admin API treats an export as a read, because that is what it is. That
+      # is a per-resource question, so it is answered in `call` rather than
+      # here: a class-level key would hide the tool from a caller who may
+      # export orders but not products.
+
+      # Exports whose rows carry a bearer instrument — a code that spends
+      # money for whoever reads it. Refused outright rather than stripped,
+      # because an export of gift cards without their codes answers nothing
+      # the merchant asked for. `Spree::Mcp::Exports` reads this list too, so
+      # a file made before this existed stays unreadable.
+      BEARER_EXPORTS = %w[gift_cards coupon_codes].freeze
+
+      permission nil
+      mutating!
+
+      param :resource, description: 'What to export: products, orders, customers',
+                       required: true
+      param :filters, type: :object,
+                      description: 'Optional Ransack filters, e.g. {"status_eq": "active"}'
+
+      def call(resource:, filters: nil)
+        export_class = export_class_for(resource)
+        return unknown_resource(resource) if export_class.nil?
+
+        required = "read_#{export_class.required_scope}"
+        unless context.holds?(required)
+          return { error: "You do not have permission to export #{resource.to_s.tr('_', ' ')}." }
+        end
+
+        # Refused here rather than at read, so the merchant is not left with a
+        # generated file of live codes waiting to be collected.
+        if Spree::AgentTools::CreateExport::BEARER_EXPORTS.include?(resource.to_s)
+          return { error: "#{resource.to_s.tr('_', ' ').capitalize} carry codes that spend money for " \
+                          'whoever reads them, so they cannot be exported here. Download them from ' \
+                          'the dashboard instead.' }
+        end
+
+        export = export_class.new(
+          store: context.store,
+          # For a signed-in admin the export builds an ability from this user,
+          # so the file holds exactly the records that admin could see,
+          # record-level rules included. For an API key there is no user and
+          # no ability: the scope check above is the whole filter, which is
+          # how the Admin API treats key requests everywhere else.
+          user: context.user,
+          format: 'csv',
+          search_params: filters.presence
+        )
+
+        refusal = unauthorized(:create, export)
+        return refusal if refusal
+
+        # Saving publishes `export.created`, which is what actually enqueues
+        # generation. (`generate_async` hands a raw id to a job that expects a
+        # prefixed one — the subscriber is the working path.)
+        return { error: export.errors.full_messages.to_sentence } unless export.save
+
+        {
+          ok: true,
+          id: export.prefixed_id,
+          resource: resource.to_s,
+          # Generation is a background job, so there is no file yet. Naming
+          # the tool that finishes the job keeps the model from sending the
+          # merchant to the dashboard for something it can fetch itself.
+          # Naming the MCP resource matters: a client that can read one will
+          # otherwise never learn the file is there, and the model reports a
+          # download path to a merchant instead of reading the rows itself.
+          resource_uri: "spree+export://#{export.prefixed_id}",
+          message: 'The export is being prepared. Once it is ready you can read its contents ' \
+                   "from the MCP resource spree+export://#{export.prefixed_id}, or call " \
+                   "get_resource (resource: \"exports\", id: \"#{export.prefixed_id}\") for its " \
+                   'status and a download_url to hand the merchant.'
+        }
+      end
+
+      def summary(arguments)
+        label = arguments[:resource].to_s.tr('_', ' ')
+        return "Export all #{label}" if arguments[:filters].blank?
+
+        filters = arguments[:filters].keys.map { |key| key.to_s.tr('_', ' ') }.join(', ')
+        "Export #{label} filtered by #{filters}"
+      end
+
+      private
+
+      # Only the export kinds Spree actually ships, resolved by name rather
+      # than constantized from model input.
+      def export_class_for(resource)
+        key = resource.to_s.downcase
+        Spree::Export.descendants.find do |klass|
+          klass.name.demodulize.underscore == key
+        end
+      end
+
+      def unknown_resource(resource)
+        {
+          error: "Cannot export #{resource.inspect}",
+          available: Spree::Export.descendants.map { |k| k.name.demodulize.underscore }.sort
+        }
+      end
+    end
+  end
+end

data/app/tools/spree/agent_tools/create_import.rb

@@ -0,0 +1,117 @@
+module Spree
+  module AgentTools
+    # Starts a CSV import from a file the merchant provided.
+    #
+    # Gated on the WRITE scope of what is being imported, computed per call —
+    # a customers import needs `write_customers`, a products import
+    # `write_products`. A single class-level key could not say that, which is
+    # why the resource reached the map read-only; `create_export` answers the
+    # same question the same way.
+    #
+    # Creating the import reads the file's header row and proposes a column
+    # mapping. Nothing is written to the catalog until that mapping is
+    # confirmed, so this is the safe half of the wizard: the merchant still
+    # sees what the columns were taken to mean before any row lands.
+    class CreateImport < Spree::AgentTool
+      tool_name 'create_import'
+      description 'Start a CSV import from a file the merchant provided. Call upload_file ' \
+                  'first and pass the file_id it returns. The columns are read and a mapping ' \
+                  'proposed; no records change until the mapping is confirmed.'
+      # Per-resource, answered in `call` — a class-level key would hide the
+      # tool from a caller who may import one kind of record but not another.
+      permission nil
+      mutating!
+
+      param :resource, description: 'What the file holds: products, customers, purchase_orders',
+                       required: true
+      param :file_id, description: 'The file_id upload_file returned', required: true
+
+      def call(resource:, file_id:)
+        import_class = import_class_for(resource)
+        return unknown_resource(resource) if import_class.nil?
+
+        required = "write_#{import_class.required_scope}"
+        unless context.holds?(required)
+          return { error: "You do not have permission to import #{resource.to_s.tr('_', ' ')}." }
+        end
+
+        start(import_class, resource, file_id)
+      end
+
+      def summary(arguments)
+        "Start a #{arguments[:resource].to_s.tr('_', ' ')} import"
+      end
+
+      private
+
+      def start(import_class, resource, file_id)
+        owner = importing_user
+        return { error: no_user_error } if owner.nil?
+
+        import = import_class.new(store: context.store, user: owner)
+        import.attachment = file_id
+
+        refusal = unauthorized(:create, import)
+        return refusal if refusal
+        return { error: import.errors.full_messages.to_sentence } unless import.save
+
+        mapping = Spree.import_start_mapping_workflow.call(import: import)
+        return { error: mapping_failure(mapping, import) } unless mapping.success?
+
+        {
+          ok: true,
+          id: import.prefixed_id,
+          resource: resource.to_s,
+          status: import.reload.status,
+          # The mapping is the point of this step: the model should read it
+          # back and tell the merchant what the columns were taken to mean
+          # before anything is written.
+          next_step: "Call describe_import_mapping with id #{import.prefixed_id} to see the " \
+                     'columns, then confirm it to run the import.',
+          dashboard_path: ResourceMap.find('imports')&.dashboard_path_for(import)
+        }
+      rescue ::CSV::MalformedCSVError, EncodingError => e
+        { error: "That file could not be read as CSV: #{e.message}" }
+      rescue ActiveSupport::MessageVerifier::InvalidSignature, ActiveRecord::RecordNotFound
+        { error: "#{file_id.inspect} is not a file this store uploaded. Call upload_file first." }
+      rescue ActiveStorage::FileNotFoundError
+        { error: 'That upload did not finish — its bytes are missing. Upload the file again.' }
+      end
+
+      def mapping_failure(result, import)
+        error = result.error
+        message = error.try(:value).is_a?(String) ? error.value : error.to_s
+
+        message.presence || import.processing_errors.presence || 'The file could not be mapped.'
+      end
+
+      # An import belongs to a person — it emails them when it finishes and
+      # its failed rows are theirs to retry. A grant carries the admin who
+      # approved it; a standing key carries whoever minted it, which is the
+      # same fallback the Admin API uses.
+      def importing_user
+        return context.user if context.user.present?
+
+        creator = context.api_key&.created_by
+        creator if creator.is_a?(Spree.admin_user_class)
+      end
+
+      def no_user_error
+        'An import has to belong to a staff member, and this credential names none. ' \
+          'Connect an agent through the dashboard, or start the import there.'
+      end
+
+      def import_class_for(resource)
+        key = resource.to_s.downcase
+        Spree::Import.available_types.find { |klass| klass.name.demodulize.underscore == key }
+      end
+
+      def unknown_resource(resource)
+        {
+          error: "Cannot import #{resource.inspect}.",
+          available: Spree::Import.available_types.map { |k| k.name.demodulize.underscore }.sort
+        }
+      end
+    end
+  end
+end

data/app/tools/spree/agent_tools/create_media.rb

@@ -0,0 +1,81 @@
+module Spree
+  module AgentTools
+    # Puts a file into the media library, optionally on a product.
+    #
+    # Creating media needs a file, which an agent had no way to supply until
+    # `upload_file` existed — which is why the resource reached the map
+    # read-only. The id that tool returns is what this one takes.
+    #
+    # A row with no owner is a library file: uploaded, not yet placed. Naming
+    # a product places it in that product's gallery, which is what a merchant
+    # handing over photographs usually means.
+    class CreateMedia < Spree::AgentTool
+      tool_name 'media_create'
+      description 'Add an uploaded file to the media library, or straight onto a product. ' \
+                  'Call upload_file first and pass the file_id it returns. Without a product ' \
+                  'the file sits in the library for the merchant to place later.'
+      permission 'write_media'
+      mutating!
+
+      param :file_id, description: 'The file_id upload_file returned', required: true
+      param :product_id, description: "A product's prefixed id, to place the file in its gallery"
+      param :alt, description: 'Alt text describing the image, for accessibility and SEO'
+
+      def call(file_id:, product_id: nil, alt: nil)
+        # Placement is the path: nested under a product puts the file in that
+        # product's gallery, the flat one leaves it in the library. The
+        # endpoint resolves the parent, checks it and verifies the signed id,
+        # so there is nothing to look up here first.
+        path = if product_id.present?
+                 "/api/v3/admin/products/#{product_id}/media"
+               else
+                 '/api/v3/admin/media'
+               end
+
+        response = ApiDispatch.new(context).call(
+          method: :post, path: path, body: { signed_id: file_id, alt: alt.presence }.compact
+        )
+        unless response.success?
+          # The endpoint speaks about signed references in general, since many
+          # of its parameters are one. Here it is always a file, so the
+          # refusal names the tool that produces a valid id.
+          message = response.error_message
+          if response.status == 422 && message.to_s.match?(/signed reference/i)
+            message = "#{file_id.inspect} is not a file this store uploaded, or it has expired. " \
+                      'Call upload_file first and pass the file_id it returns.'
+          end
+
+          return { error: message }
+        end
+
+        media = response.data.to_h
+
+        {
+          ok: true,
+          id: media['id'],
+          filename: media['filename'],
+          media_type: media['media_type'],
+          product_id: product_id.presence,
+          # The media library has no page of its own in the map, so the link
+          # that helps is the product's — where the merchant will look at it.
+          dashboard_path: product_id.presence && dashboard_path_for(product_id)
+        }.compact
+      end
+
+      def summary(arguments)
+        return "Add a file to #{arguments[:product_id]}'s gallery" if arguments[:product_id].present?
+
+        'Add a file to the media library'
+      end
+
+      private
+
+      def dashboard_path_for(product_id)
+        path = ResourceMap.find('products')&.dashboard_path
+        return if path.blank?
+
+        format(path, id: product_id)
+      end
+    end
+  end
+end