huginn_bigcommerce_product_agent 1.10.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4b3e2536acd4ff18f83977f51c923c42e1a3eb53c3795d4f97ac08794c25682
-  data.tar.gz: a58f917ba53ae85c77b9b27f3e7874d5f0aec59239c16e2d6ccdc37b1d30b7b0
+  metadata.gz: b2d3a13bdac789b3b1714c68e8794c30f0f15390c0161dd8a473d36f097f4422
+  data.tar.gz: ecc6fe4feb48b5bf7d8528951fd0bcccd41b095f9b1070f73e4d41b5b31908cd
 SHA512:
-  metadata.gz: 3cb5d5996d73be6a66c06ade306ee2a6e79a0f95169aeca83df39df6db17c855cce8c6620541999d256a6d164c239d83b72515921ca3897534849c2ed39d2e74
-  data.tar.gz: 4f9576be2448f833da6c077865538769e8a2553d3abcfa1fd0c6d9bdb2f887b7ae464c0577d0d0f2c6a852ad880284bc3431b5ab89c2839db9a091a88ab20693
+  metadata.gz: db7b3003393f5b1c4e741a6be04b3bfb8bfd7be7aaf0cd006d7dd03112da997edb0efac33f2d5e41d5bc1f2d128a67c6be5c68b76b9be9b20bad4e7fbc397680
+  data.tar.gz: 1d18a0e667d3216a194816ded4f4c523dffe4eeda9d7a84186285f6a6e53ea4d14f2f8e28b2333b5de65b517e5e1bb2149c77cd7a53f659f8a65e352b266257a

data/lib/client/custom_field.rb

@@ -3,19 +3,38 @@ module BigcommerceProductAgent
         class CustomField < AbstractClient
             @uri_base = 'catalog/products/:product_id/custom-fields/:custom_field_id'
 
+            def get_for_product(product_id)
+              return [] if product_id.blank?
+
+              response = client.get(uri(product_id: product_id))
+              return response.body['data']
+            end
+
             def create(product_id, payload)
-                response = client.post(uri(product_id: product_id), payload.to_json)
+                response = client.post(
+                  uri(product_id: product_id),
+                  payload.to_json
+                )
+
                 return response.body['data']
             end
 
             def update(product_id, payload)
                 id = payload.delete('id')
-                response = client.put(uri(product_id: product_id, custom_field_id: id), payload.to_json)
+                response = client.put(
+                  uri(product_id: product_id, custom_field_id: id),
+                  payload.to_json
+                )
+
                 return response.body['data']
             end
 
             def delete(product_id, custom_field_id)
+              begin
                 client.delete(uri(product_id: product_id, custom_field_id: custom_field_id))
+              rescue Faraday::Error::ClientError => e
+                  raise e, "\n#{e.message}\nFailed to delete custom_field with id = #{custom_field_id}\nfor product with id = #{product_id}\n", e.backtrace
+              end
             end
 
             def upsert(product_id, payload)

data/lib/client/meta_field.rb

@@ -10,30 +10,33 @@ module BigcommerceProductAgent
               return response.body['data']
             end
 
-            def create(meta_field)
+            def create(product_id, meta_field)
               response = client.post(
-                uri(product_id: meta_field[:resource_id]),
+                uri(product_id: product_id),
                 meta_field.to_json
               )
 
               return response.body['data']
             end
 
-            def update(meta_field)
+            def update(product_id, meta_field)
+              id = meta_field.delete('id')
               response = client.put(
-                uri(product_id: meta_field[:resource_id], meta_field_id: meta_field[:id]),
+                uri(product_id: product_id, meta_field_id: id),
                 meta_field.to_json
               )
 
               return response.body['data']
             end
 
-            def upsert(meta_field)
+            def upsert(product_id, meta_field)
+              meta_field['id'] = meta_field.delete(:id) unless meta_field[:id].nil?
+
               begin
-                if meta_field[:id]
-                  return update(meta_field)
+                if meta_field['id']
+                  return update(product_id, meta_field)
                 else
-                  return create(meta_field)
+                  return create(product_id, meta_field)
                 end
               rescue Faraday::Error::ClientError => e
                 puts e.inspect

data/lib/client/product.rb

@@ -8,11 +8,23 @@ module BigcommerceProductAgent
                     response = client.put(uri(product_id: id), payload.to_json) do |request|
                         request.params.update(params) if params
                     end
+
+                    return response.body['data']
                 rescue Faraday::Error::ClientError => e
                     raise e, "\n#{e.message}\nFailed to update product with payload = #{payload.to_json}\n", e.backtrace
                 end
+            end
+
+            def update_batch(payload, params={})
+              begin
+                  response = client.put(uri(), payload.to_json) do |request|
+                      request.params.update(params) if params
+                  end
 
-                return response.body['data']
+                  return response.body['data']
+              rescue Faraday::Error::ClientError => e
+                  raise e, "\n#{e.message}\nFailed to update product batch with payload = #{payload.to_json}\n", e.backtrace
+              end
             end
 
             def delete(id)
@@ -25,36 +37,40 @@ module BigcommerceProductAgent
                     response = client.post(uri, payload.to_json) do |request|
                         request.params.update(params) if params
                     end
+
+                    return response.body['data']
                 rescue Faraday::Error::ClientError => e
                     raise e, "\n#{e.message}\nFailed to create product with payload = #{payload.to_json}\n", e.backtrace
                 end
-
-                return response.body['data']
             end
 
             def upsert(payload, params={})
-                if payload[:id]
-                    return update(payload[:id], payload, params)
+                payload['id'] = payload.delete(:id) unless payload[:id].nil?
+                if payload['id']
+                    return update(payload['id'], payload, params)
                 else
                     return create(payload, params)
                 end
             end
 
-            def get_by_skus(skus, include = %w[custom_fields modifiers])
+            # When using sku:in you must specify the fields you want returned.
+            def get_by_skus(skus, include = %w[custom_fields modifiers], include_fields = %w[sku])
                 products = index({
                     'sku:in': skus.join(','),
                     include: include.join(','),
+                    include_fields: include_fields.join(','),
                 })
 
-                map = {}
-
-                products.each do |product|
-                    map[product['sku']] = product
-                end
+                return products
+            end
 
-                map
+            def disable(productId)
+              upsert({ id: productId, is_visible: false })
             end
 
+            def enable(productId)
+              upsert({ id: productId, is_visible: true })
+            end
         end
     end
 end

data/lib/huginn_bigcommerce_product_agent/bigcommerce_product_agent.rb

@@ -3,434 +3,484 @@
 require 'json'
 
 module Agents
-    class BigcommerceProductAgent < Agent
-        include WebRequestConcern
+  class BigcommerceProductAgent < Agent
+    include WebRequestConcern
+
+    can_dry_run!
+    default_schedule 'never'
+
+    # TODO:   Provide a more detailed agent description. Including details of
+    # each option and how that option is used
+    description <<-MD
+      Takes an array of related products and upserts them into BigCommerce.
+    MD
+
+    def default_options
+      {
+        'store_hash' => '',
+        'client_id' => '',
+        'access_token' => '',
+        'custom_fields_map' => {},
+        'meta_fields_map' => {},
+        'meta_fields_namespace' => '',
+        'not_purchasable_format_list' => [],
+        'should_disambiguate' => false,
+
+      }
+    end
 
-        can_dry_run!
-        default_schedule 'never'
+    def validate_options
+        unless options['store_hash'].present?
+          errors.add(:base, 'store_hash is a required field')
+        end
 
-        description <<-MD
-            Takes a generic product interface && upserts that product in BigCommerce.
-        MD
+        unless options['client_id'].present?
+          errors.add(:base, 'client_id is a required field')
+        end
 
-        def modes
-            %w[
-                variants
-                option_list
-            ]
+        unless options['access_token'].present?
+          errors.add(:base, 'access_token is a required field')
         end
 
-        def default_options
-            {
-                'store_hash' => '',
-                'client_id' => '',
-                'access_token' => '',
-                'custom_fields_map' => {},
-                'meta_fields_map' => {},
-                'meta_fields_namespace' => '',
-                'mode' => modes[0],
-                'not_purchasable_format_list' => [],
-                'should_disambiguate' => false
-            }
+        unless options['custom_fields_map'].is_a?(Hash)
+          errors.add(:base, 'if provided, custom_fields_map must be a hash')
         end
 
-        def validate_options
-            unless options['store_hash'].present?
-                errors.add(:base, 'store_hash is a required field')
-            end
+        unless options['meta_fields_map'].is_a?(Hash)
+          errors.add(:base, 'if provided, meta_fields_map must be a hash')
+        end
 
-            unless options['client_id'].present?
-                errors.add(:base, 'client_id is a required field')
-            end
+        if options['meta_fields_map']
+          if options['meta_fields_namespace'].blank?
+            errors.add(:base, 'if meta_fields_map is provided, meta_fields_namespace is required')
+          end
+        end
 
-            unless options['access_token'].present?
-                errors.add(:base, 'access_token is a required field')
-            end
+        if options['not_purchasable_format_list'].present? && !options['not_purchasable_format_list'].is_a?(Array)
+          errors.add(:base, 'not_purchasable_format_list must be an Array')
+        end
 
-            unless options['custom_fields_map'].is_a?(Hash)
-                errors.add(:base, 'if provided, custom_fields_map must be a hash')
-            end
+        if options.has_key?('should_disambiguate') && boolify(options['should_disambiguate']).nil?
+          errors.add(:base, 'when provided, `should_disambiguate` must be either true or false')
+        end
 
-            unless options['meta_fields_map'].is_a?(Hash)
-                errors.add(:base, 'if provided, meta_fields_map must be a hash')
-            end
+        if options.has_key?('track_inventory') && boolify(options['track_inventory']).nil?
+          errors.add(:base, 'when provided, `track_inventory` must be true or false')
+        end
 
-            if options['meta_fields_map']
-                if options['meta_fields_namespace'].blank?
-                    errors.add(:base, 'if meta_fields_map is provided, meta_fields_namespace is required')
-                end
-            end
+    end
 
-            unless options['mode'].present? && modes.include?(options['mode'])
-                errors.add(:base, "mode is a required field and must be one of: #{modes.join(', ')}")
-            end
+    def working?
+      received_event_without_error?
+    end
 
-            if options['not_purchasable_format_list'].present? && !options['not_purchasable_format_list'].is_a?(Array)
-                errors.add(:base, 'not_purchasable_format_list must be an Array')
-            end
+    def check
+      initialize_clients
+      handle interpolated['payload'].presence || {}
+    end
 
-            if options.has_key?('should_disambiguate') && boolify(options['should_disambiguate']).nil?
-                errors.add(:base, 'when provided, `should_disambiguate` must be either true or false')
-            end
+    def receive(incoming_events)
+      initialize_clients
+      incoming_events.each do |event|
+        handle(event)
+      end
+    end
 
+    def handle(event)
+      data = event.payload
+      raw_products = data['products']
+      results = []
+
+      # Loop through the provided raw_products and perform the upsert
+      # This process will upsert the core product record and the custom/meta
+      # fields from the Acumen data.
+      additional_data = {
+        additional_search_terms: [],
+      }
+
+      raw_products.each do |raw_product|
+        additional_data[:additional_search_terms].push(raw_product['sku'])
+      end
+
+      bc_products = lookup_existing_products(raw_products)
+      existing_skus = bc_products.map { |p| p['sku'] }
+
+      # This agent requires us to make several requests due to limitations in the BigCommerce API.
+      # Specifically, Product records must be created and deleted individually, and, though meta fields can
+      # be managed in "bulk", the batch is limited to specific product IDs.
+      #
+      # Additionally, this agent sets a `related_product_ids` field as a CSV string of each product ID in
+      # the bundle. Because this field expects the BigCommerce ID, this has to happen _after_ product
+      # creation / deletion.
+      #
+      # For the sake of performance, we group products into three buckets: create, delete, update.
+      # From there, we run through the following process:
+      #
+      #     *  Create new products
+      #     *  Delete discontinued products
+      #     *  Update existing products & custom fields
+      #     *  Update meta fields
+      #
+      # The existing product update will include data for products created in step one. This is intentional
+      # because the update step allows us to populate custom fields in bulk (including the `related_product_ids`
+      # field), so we still come out ahead in terms of overall performance.
+
+      to_create = raw_products.select { |p| p['productAvailability'] != 'not available' && !existing_skus.include?(p['sku'])}
+      to_delete = raw_products.select { |p| p['productAvailability'] == 'not available' && existing_skus.include?(p['sku'])}
+      to_update = raw_products.select { |p| p['productAvailability'] != 'not available' && existing_skus.include?(p['sku'])}
+
+      mapped_products = [] # Contains an array of { :bc_payload, :raw_product } hashes
+
+      #  Delete all inactive products
+      to_delete.each do |p|
+          bc_product = bc_products.find { |bc| bc['sku'] == p['sku'] }
+          delete_inactive_product(bc_product)
+      end
+
+      # A Note regarding the nil checks below. In order to improve the efficiency
+      # of this agent, we process requests in batch wherever possible. However,
+      # we don't want errors with one product to prevent others in the bundle from
+      # processing.
+      #
+      # Methods that process single records intentionally return `nil` in the event
+      # of an error to facilitate this, and `nil` entries are excluded from the
+      # batch processes. Additionally, any such processing errors are emitted as
+      # error events with `status: 500` to facilitate reporting.
+
+      #-----   Handle the creation of any new products   -----#
+      to_create.each do |raw_product|
+        bc_product = create_new_product(raw_product, additional_data)
+        unless bc_product.nil?
+          mapped_products.push({ bc_payload: bc_product, raw_product: raw_product })
         end
+      end
 
-        def working?
-            received_event_without_error?
-        end
+      #-----   Process updates for existing products   -----#
+      to_update.each do |raw_product|
+        bc_product = bc_products.find { |bc| bc['sku'] == raw_product['sku'] }
+        mapped_product = process_updates(raw_product, bc_product, additional_data)
 
-        def check
-            initialize_clients
-            handle interpolated['payload'].presence || {}
+        unless mapped_product.nil?
+          mapped_products.push(mapped_product)
         end
+      end
+
+      #-----   Handle final upserts   -----#
+      unless mapped_products.blank?
+        # NOTE: An empty array here likely indicates that a title has been removed
+        # from sale completely and is not available in any format. Most of the
+        # time, mapped_products should have at least one item.
+        #
+        # In rare cases, it may mean that all products resulted in a processing
+        # error, but since those are tracked individually, we don't need to issue
+        # any errors here.
+        upsert_products(mapped_products)
+      end
+    end
 
-        def receive(incoming_events)
-            initialize_clients
-            incoming_events.each do |event|
-                handle(event)
-            end
-        end
+    # Attempt to find an existing BigCommerce product by SKU
+    # Returns nil if no matching product is found.
+    def lookup_existing_products(raw_products)
+      begin
+        bc_products = @product_client.get_by_skus(raw_products.map { |r| r['sku'] })
+
+        return bc_products
+      rescue => e
+        create_event payload: {
+          status: 500,
+          scope: 'lookup_existing_products',
+          message: e.message,
+          trace: e.backtrace.join('\n'),
+          raw_product: raw_products,
+        }
+
+        raise e
+        # This exception is intentionally rethrown because it means we were unable
+        # lookup existing BigCommerce records. (If there were no matching SKUs, the
+        # response would be an empty array). In this case, we don't have enough
+        # information to accurately process the incoming raw products, so we must
+        # fail.
+      end
+    end
 
-        def handle(event)
-            method_name = "handle_#{interpolated['mode']}"
-            if self.respond_to?(method_name, true)
-                self.public_send(method_name, event)
-            else
-                raise "'#{interpolated['mode']}' is not a supported mode"
-            end
+    def delete_inactive_product(bc_product)
+      begin
+        @product_client.delete(bc_product['id'])
+      rescue => e
+        create_event payload: {
+          status: 500,
+          scope: 'delete_inactive_product',
+          message: e.message,
+          trace: e.backtrace.join('\n'),
+          bc_product: bc_product,
+        }
+      end
+    end
+
+    # Handles the creation of new product records
+    def create_new_product(raw_product, additional_data)
+      begin
+        bc_payload = map_product(raw_product, nil, additional_data)
+        custom_fields = map_custom_fields(raw_product, nil)
+        bc_payload['custom_fields'] = custom_fields[:upsert]
+        return @product_client.create(bc_payload, { include: 'custom_fields' })
+      rescue => e
+        create_event payload: {
+          status: 500,
+          scope: 'create_product',
+          message: e.message(),
+          trace: e.backtrace.join('\n'),
+          raw_product: raw_product,
+          product_data: bc_payload,
+        }
+
+        return nil
+      end
+    end
+
+    # Generates an update payload for the provided product records
+    # Returns a hash containing { :bc_payload, :raw_product }
+    def process_updates(raw_product, bc_product, additional_data)
+      custom_fields = map_custom_fields(raw_product, bc_product)
+
+      custom_fields[:delete].each do |field|
+        begin
+          # Delete custom fields that are no longer used
+          @custom_field_client.delete(bc_product['id'], field['id'])
+        rescue => e
+          create_event payload: {
+            status: 500,
+            scope: 'delete_custom_fields',
+            message: e.message(),
+            trace: e.backtrace.join('\n'),
+            product_id: bc_product['id'],
+            deletes: custom_fields[:delete]
+          }
         end
+      end
 
-        # 1. upsert product
-        # 2. upsert option & option_values
-        # 3. delete old option_values
-        #     - NOTE: deleting an option_value also deletes the variant
-        #       associated with the option_value
-        # 4. upsert variants
-        #     - NOTE: because deleting option values deletes variants
-        #       we need to fetch the variants AFTER deletion has occurred.
-        #     - NOTE: by deleting variants in #3 if option_values on an
-        #       existing variant changes over time, we're effectively deleting
-        #       and then re-adding the variant. Could get weird.
-        def handle_variants(event)
-            product = event.payload
-
-            split = get_mapper(:ProductMapper).split_digital_and_physical(
-              product,
-              interpolated['custom_fields_map']
-            )
-            physical = split[:physical]
-            digital = split[:digital]
-
-            wrapper_skus = {
-                physical: get_mapper(:ProductMapper).get_wrapper_sku(physical),
-                digital: get_mapper(:ProductMapper).get_wrapper_sku(digital),
-            }
+      bc_payload = map_product(raw_product, bc_product, additional_data)
 
-            bc_products = @product.get_by_skus(
-                wrapper_skus.map {|k,v| v},
-                %w[custom_fields options]
-            )
-            #save skus
-            digital_skus = []
-            physical_skus = []
-            if split[:digital] and split[:physical]
-                digital_skus.concat([wrapper_skus[:digital]])
-                digital_skus.concat(get_mapper(:ProductMapper).get_product_skus(split[:digital])).join(",")
-                physical_skus.concat([wrapper_skus[:physical]])
-                physical_skus.concat(get_mapper(:ProductMapper).get_product_skus(split[:physical])).join(",")
-            end
+      if bc_payload.present?
+        bc_payload['custom_fields'] = custom_fields[:upsert]
+        return { bc_payload: bc_payload, raw_product: raw_product }
+      else
+        return nil
+      end
+    end
 
-            # upsert wrapper products
-            split.each do |type, product|
-                is_digital = type == :digital ? true : false
-
-                # modify digital
-                if is_digital
-                    product['name'] = "#{product['name']} (Digital)"
-                end
-
-                # Ignatius Press -- some products have the same name and must be disambiguated.
-                # ...by adding a list of the product types (hardback, paperback, etc.) to their names
-                if boolify(options['should_disambiguate'])
-                    product['page_title'] = product['name']
-                    product['name'] += " |~ " + product['model'].map { |m|
-                       m['additionalProperty'].find { |p|
-                           p['propertyID'] == 'option'
-                       }['value']
-                    }.join(", ")
-                end
-
-                wrapper_sku = wrapper_skus[type]
-                bc_product = bc_products[wrapper_sku]
-                variant_option_name = get_mapper(:OptionMapper).variant_option_name
-                bc_option = !bc_product.nil? ? bc_product['options'].select {|opt| opt['display_name'] === variant_option_name}.first : nil
-
-                search_skus = is_digital ? physical_skus : digital_skus
-                # ##############################
-                # 1. update wrapper product
-                # ##############################
-                upsert_result = upsert_product(wrapper_sku, product, bc_product, is_digital, search_skus)
-                bc_product = upsert_result[:product]
-
-                # clean up custom/meta fields. there are not batch operations so we might as well do them here.
-                custom_fields_delete = upsert_result[:custom_fields_delete].select {|field| field['name'] != 'related_product_id'}
-                clean_up_custom_fields(custom_fields_delete)
-                meta_fields = update_meta_fields(
-                    upsert_result[:meta_fields_upsert],
-                    upsert_result[:meta_fields_delete],
-                )
-
-                bc_product['meta_fields'] = meta_fields
-
-                bc_products[wrapper_sku] = bc_product
-                product_id = bc_products[wrapper_sku]['id']
-
-                # ##############################
-                # 2. upsert option & option_values
-                # ##############################
-                option_values_map = get_mapper(:ProductMapper).get_sku_option_label_map(product)
-                option_values = option_values_map.map {|k,v| v}
-                option_value_operations = get_mapper(:OptionMapper).option_value_operations(bc_option, option_values)
-                option = get_mapper(:OptionMapper).map(product_id, bc_option, option_value_operations[:create])
-                bc_option = @product_option.upsert(product_id, option)
-
-                # ##############################
-                # 3. delete old option_values
-                # ##############################
-                @product_option_value.delete_all(bc_option, option_value_operations[:delete])
-
-                # ##############################
-                # 4. upsert variants
-                # ##############################
-                variant_skus = get_mapper(:ProductMapper).get_product_skus(product)
-                bc_variants = @product_variant.index(product_id)
-                mapped_variants = product['model'].map do |variant|
-                    bc_variant = bc_variants.select {|v| v['sku'] === variant['sku']}.first
-                    opt = get_mapper(:ProductMapper).get_option(variant)
-                    bc_option_value = bc_option['option_values'].select {|ov| ov['label'] == opt}.first
-
-                    option_value = get_mapper(:VariantMapper).map_option_value(bc_option_value['id'], bc_option['id'])
-
-                    get_mapper(:VariantMapper).map(
-                        variant,
-                        [option_value],
-                        product_id,
-                        bc_variant.nil? ? nil : bc_variant['id'],
-                        interpolated['not_purchasable_format_list'],
-                        bc_option_value
-                    )
-                end
-
-                bc_product['variants'] = @variant.upsert(mapped_variants)
-            end
+    # Sends a batch update request for the provided products
+    # NOTE: This process also sets the `related_product_ids` custom field
+    def upsert_products(mapped_products)
+      product_ids = mapped_products.map { |p| p[:bc_payload]['id'] }
+      results = {}
 
-            bc_physical = bc_products[wrapper_skus[:physical]]
-            bc_digital = bc_products[wrapper_skus[:digital]]
-            is_delete_physical = split[:physical].nil? && bc_physical
-            is_delete_digital = split[:digital].nil? && bc_digital
-
-            # ##############################
-            # clean up products that no longer exist
-            # ##############################
-            if is_delete_physical
-                bc_product = bc_products[wrapper_skus[:physical]]
-                @product.delete(bc_product['id'])
-                bc_physical = false
-                bc_product.delete(wrapper_skus[:physical])
-            end
+      product_data = mapped_products.map do |p|
+        bc_payload = p[:bc_payload]
+        raw_product = p[:raw_product]
 
-            if is_delete_digital
-                bc_product = bc_products[wrapper_skus[:digital]]
-                @product.delete(bc_product['id'])
-                bc_digital = false
-                bc_product.delete(wrapper_skus[:digital])
-            end
+        meta_fields = update_meta_fields(raw_product, bc_payload)
+        results[raw_product['sku']] = {
+          raw_product: raw_product,
+          meta_fields: meta_fields[:upsert],
 
-            # ##############################
-            # clean up custom field relationships
-            # ##############################
-            if bc_physical && !bc_digital
-                # clean up related_product_id on physical product
-                bc_product = bc_physical
-                related_custom_field = bc_product['custom_fields'].select {|field| field['name'] == 'related_product_id'}.first
-                @custom_field.delete(bc_product['id'], related_custom_field['id']) unless related_custom_field.nil?
-            elsif !bc_physical && bc_digital
-                # clean up related_product_id on digital product
-                bc_product = bc_digital
-                related_custom_field = bc_product['custom_fields'].select {|field| field['name'] == 'related_product_id'}.first
-                @custom_field.delete(bc_product['id'], related_custom_field['id']) unless related_custom_field.nil?
-            elsif bc_physical && bc_digital
-                # update/add related_product_id on both products
-                bc_physical_related = get_mapper(:CustomFieldMapper).map_one(bc_physical, 'related_product_id', bc_digital['id'])
-                bc_digital_related = get_mapper(:CustomFieldMapper).map_one(bc_digital, 'related_product_id', bc_physical['id'])
-                @custom_field.upsert(bc_physical['id'], bc_physical_related)
-                @custom_field.upsert(bc_digital['id'], bc_digital_related)
-            end
+        }
 
-            # ##############################
-            # emit events
-            # ##############################
-            if bc_physical
-                create_event payload: {
-                    product: bc_physical
-                }
-            end
+        #-----  Set related_product_ids  -----#
+        related_product_ids = product_ids.select { |id| id != bc_payload['id'] }
+        field = {
+          'name': 'related_product_ids',
+          'value': related_product_ids * ',' # concatenate as a CSV
+        }
 
-            if bc_digital
-                create_event payload: {
-                    product: bc_digital
-                }
-            end
+        unless related_product_ids.empty?
+          if bc_payload['custom_fields'].blank?
+            bc_payload['custom_fields'] = []
+          end
+
+          bc_payload['custom_fields'].push(field)
         end
 
-        def handle_option_list(event)
-            product = event.payload
-
-            skus = get_mapper(:ProductMapper).get_product_skus(product)
-            wrapper_sku = get_mapper(:ProductMapper).get_wrapper_sku(product)
-            all_skus = [].push(*skus).push(wrapper_sku)
-            bc_products = @product.get_by_skus(all_skus)
-
-            # upsert child products
-            bc_children = []
-            custom_fields_delete = []
-            meta_fields_upsert = []
-            meta_fields_delete = []
-
-            skus.each do |sku|
-                bc_product = bc_products[sku]
-                result = upsert_product(sku, product, bc_product)
-                custom_fields_delete += result[:custom_fields_delete]
-                meta_fields_upsert += result[:meta_fields_upsert]
-                meta_fields_delete += result[:meta_fields_delete]
-                bc_children.push(result[:product])
-            end
+        # return the finalized payload
+        bc_payload
+      end
 
-            # upsert wrapper
-            bc_wrapper_product = bc_products[wrapper_sku]
-            result = upsert_product(wrapper_sku, product, bc_wrapper_product)
-            custom_fields_delete += result[:custom_fields_delete]
-            meta_fields_upsert += result[:meta_fields_upsert]
-            meta_fields_delete += result[:meta_fields_delete]
-
-            is_default_map = get_mapper(:ProductMapper).get_is_default(product)
-
-            # update modifier
-            sku_option_map = get_mapper(:ProductMapper).get_sku_option_label_map(product)
-            modifier_updates = get_mapper(:ModifierMapper).map(
-                bc_wrapper_product,
-                bc_children,
-                sku_option_map,
-                is_default_map
-            )
-            @modifier.upsert(result[:product]['id'], modifier_updates[:upsert])
-
-            clean_up_custom_fields(custom_fields_delete)
-            clean_up_modifier_values(modifier_updates[:delete])
-            meta_fields = update_meta_fields(meta_fields_upsert, meta_fields_delete)
-
-            product['meta_fields'] = meta_fields
-            product['modifiers'] = modifier_updates[:upsert]
-            create_event payload: {
-                product: product,
-                parent: result[:product],
-                children: bc_children
-            }
-        end
+      begin
+        @product_client.update_batch(product_data, { include: 'custom_fields' }).each do |p|
+          result = results[p['sku']]
+          result[:custom_fields] = p['custom_fields']
+          result[:bc_product] = p
 
-        private
-
-        def initialize_clients
-            @variant = initialize_client(:Variant)
-            @product_variant = initialize_client(:ProductVariant)
-            @product_option = initialize_client(:ProductOption)
-            @product_option_value = initialize_client(:ProductOptionValue)
-            @product = initialize_client(:Product)
-            @custom_field = initialize_client(:CustomField)
-            @meta_field = initialize_client(:MetaField)
-            @modifier = initialize_client(:Modifier)
-            @modifier_value = initialize_client(:ModifierValue)
+          create_event payload: {
+            product: result,
+            status: 200,
+          }
         end
+      rescue => e
+        create_event payload: {
+          status: 500,
+          scope: 'upsert_products',
+          message: e.message,
+          trace: e.backtrace.join('\n'),
+          product_data: product_data,
+        }
+      end
+    end
 
-        def initialize_client(class_name)
-            klass = ::BigcommerceProductAgent::Client.const_get(class_name.to_sym)
-            return klass.new(
-                interpolated['store_hash'],
-                interpolated['client_id'],
-                interpolated['access_token']
-            )
-        end
+    # Map the raw_product record to bc_product fields. The bc_product passed in may be null
+    # if the product does not exist yet in BigCommerce.
+    def map_product(raw_product, bc_product, additional_data)
+      bc_payload = nil
 
-        def get_mapper(class_name)
-            return ::BigcommerceProductAgent::Mapper.const_get(class_name.to_sym)
+      begin
+        track_inventory = boolify(options['track_inventory']).nil? ? true : boolify(options['track_inventory'])
+        bc_payload = get_mapper(:ProductMapper).map_payload(raw_product, additional_data, track_inventory)
+        bc_payload['id'] = bc_product['id'] unless bc_product.nil? || bc_product['id'].nil?
+        # NOTE: bc_product will be nil when this is called with `to_create` products
+
+        if bc_payload[:type] == 'digital'
+          bc_payload[:name].concat(' (Digital)')
         end
 
-        def upsert_product(sku, product, bc_product = nil, is_digital=false, search_skus=[])
-            custom_fields_updates = get_mapper(:CustomFieldMapper).map(
-                interpolated['custom_fields_map'],
-                product,
-                bc_product
-            )
-
-            product_id = bc_product['id'] unless bc_product.nil?
-
-            payload = get_mapper(:ProductMapper).payload(
-                sku,
-                product,
-                product_id,
-                {
-                    additional_search_terms: search_skus,
-                    custom_fields: custom_fields_updates[:upsert]
-                },
-                is_digital,
-            )
-
-            bc_product = @product.upsert(payload, {
-                include: %w[custom_fields variants options].join(',')
-            })
-
-            # Metafields need to be managed separately. Intentionally get them _AFTER_
-            # the upsert so that we have the necessary resource_id (bc_product.id)
-            meta_fields_updates = get_mapper(:MetaFieldMapper).map(
-                interpolated['meta_fields_map'],
-                product,
-                bc_product,
-                @meta_field.get_for_product(bc_product['id']),
-                interpolated['meta_fields_namespace']
-            )
-
-            {
-                product: bc_product,
-                custom_fields_delete: custom_fields_updates[:delete],
-                meta_fields_upsert: meta_fields_updates[:upsert],
-                meta_fields_delete: meta_fields_updates[:delete]
-            }
+        # BigCommerce requires that product names be unique. In some cases, (like book titles from multiple sources),
+        # this may be hard to enforce. In those cases, the product SKUs should still be unique, so we append the SKU
+        # to the product title with a `|~` separator. We then set the `page_title` to the original product name so
+        # users don't see system values.
+        #
+        # page_title is the user-facing display value for product pages.
+        if boolify(options['should_disambiguate'])
+           bc_payload[:page_title] = bc_payload[:name]
+           bc_payload[:name] = bc_payload[:name] + " |~ " + raw_product['sku']
         end
 
-        def clean_up_custom_fields(custom_fields)
-            custom_fields.each do |field|
-                @custom_field.delete(field['product_id'], field['id'])
+        return bc_payload
+      rescue => e
+        create_event payload: {
+          status: 500,
+          scope: 'map_product',
+          message: e.message(),
+          trace: e.backtrace.join('\n'),
+          product_payload: bc_payload,
+        }
+      end
+
+      return nil
+    end
+
+    #  Maps custom field values from the raw_product to the bc_payload
+    #  NOTE: Because custom fields can be included in product upsert requests,
+    #  this function is only _mapping_ the data.
+    def map_custom_fields(raw_product, bc_payload)
+      current_fields = bc_payload.nil? ? [] : bc_payload['custom_fields']
+
+      begin
+        return get_mapper(:CustomFieldMapper).map(options['custom_fields_map'], raw_product, bc_payload, current_fields, options['meta_fields_namespace'])
+      rescue => e
+        create_event payload: {
+          status: 500,
+          scope: 'map_custom_fields',
+          message: e.message(),
+          trace: e.backtrace.join('\n'),
+          field_map: options['custom_fields_map'],
+          raw_product: raw_product,
+          product_payload: bc_payload,
+        }
+
+        return nil
+      end
+    end
+
+    #  Manages meta field values for the provided product records.
+    #  NOTE: Because meta fields have to be managed separately, this function will
+    #  map the raw_product data and also handle any delete/create/update requests.
+    def update_meta_fields(raw_product, bc_payload)
+      current_fields = nil
+
+      begin
+        current_fields = @meta_field_client.get_for_product(bc_payload['id'])
+      rescue => e
+        create_event payload: {
+          status: 500,
+          scope: 'update_meta_fields',
+          message: "Failed to lookup existing meta fields: #{e.message()}",
+          trace: e.backtrace.join('\n'),
+          product_id: bc_payload['id'],
+        }
+
+        return nil
+      end
+
+      begin
+        fields = get_mapper(:MetaFieldMapper).map(options['meta_fields_map'], raw_product, bc_payload, current_fields, options['meta_fields_namespace'])
+
+        # Delete fields
+        fields[:delete].each do |field|
+            begin
+              @meta_field_client.delete(bc_payload['id'], field['id'])
+            rescue => e
+              create_event payload: {
+                status: 500,
+                scope: 'update_meta_fields',
+                message: "Failed to delete meta field: #{e.message()}",
+                trace: e.backtrace.join('\n'),
+                product_id: bc_payload['id'],
+                field: field,
+              }
             end
         end
 
-        def clean_up_modifier_values(modifier_values)
-            modifier_values.each do |field|
-                @modifier_value.delete(field[:product_id], field[:modifier_id], field[:value_id])
-            end
+        # Upsert fields
+        fields[:upsert].each do |field|
+          begin
+            @meta_field_client.upsert(bc_payload['id'], field)
+          rescue => e
+            create_event payload: {
+              status: 500,
+              scope: 'update_meta_fields',
+              message: "Failed to update meta field: #{e.message()}",
+              trace: e.backtrace.join('\n'),
+              product_id: bc_payload['id'],
+              field: field,
+            }
+          end
         end
 
-        def update_meta_fields(upsert_fields, delete_fields)
-            meta_fields = []
+        return fields
+      rescue => e
+        create_event payload: {
+          status: 500,
+          scope: 'update_meta_fields',
+          message: "Failed to map meta field data: #{e.message()}",
+          trace: e.backtrace.join('\n'),
+          field_map: options['meta_fields_map'],
+          raw_product: raw_product,
+          bc_payload: bc_payload,
+          current_fields: current_fields,
+        }
+
+        return nil
+      end
+    end
 
-            upsert_fields.each do |field|
-                meta_fields << @meta_field.upsert(field)
-            end
+    private
 
-            delete_fields.each do |field|
-                @meta_field.delete(field[:resource_id], field[:id])
-            end
+    def initialize_clients
+        @product_client = initialize_client(:Product)
+        @custom_field_client = initialize_client(:CustomField)
+        @meta_field_client = initialize_client(:MetaField)
+    end
 
-            meta_fields
-        end
+    def initialize_client(class_name)
+        klass = ::BigcommerceProductAgent::Client.const_get(class_name.to_sym)
+        return klass.new(
+            interpolated['store_hash'],
+            interpolated['client_id'],
+            interpolated['access_token']
+        )
+    end
+
+    def get_mapper(class_name)
+        return ::BigcommerceProductAgent::Mapper.const_get(class_name.to_sym)
     end
+  end
 end