huginn_acumen_product_agent 1.7.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f611c6b9e7567e84ec03753277031b227c70fee3afe17cfbf35be0c185932b4f
-  data.tar.gz: ecfc5e4acee56876eee9b4c3de78db3f6e40ff1cce60d5a6e834c75dae97523f
+  metadata.gz: a0c47e2991b9e5c568b8b7762fbd9286b818401cc8d9f6cbc6b4e9af4d93c3a2
+  data.tar.gz: 994118245c433230a1b1ea15043bbb9e7d5f83af241c0c2bfae3362d833acb46
 SHA512:
-  metadata.gz: 8ccf91cb1986314c492cbe9b0b189503504705bc6521a8f7861bbef9338bdb2e27ebb2036b5b595c55c33c52f1cb81e4534ca9686b3d2a67cd1fa6dfa2389e6b
-  data.tar.gz: 63b33acb6744b016c1f08ddf409d6580c2e78e57b46c93ccfe91326b7233b2dc54db09cd5fb52ee6eb49f6178f0439ee0b9518d87633baefcd0e52a5a7af9e10
+  metadata.gz: 2349ea217eb714518d1c995703a9167527b8589106c38e13559835d621eadb155a90430d6c63927115d3d062369f52005f57b62f5d18a61c0bd2c501dae47401
+  data.tar.gz: 03f03158f7e226fd518c49d04867f1ae00424992f60aa71b31fc9ab9f7a5bd1aff366a49598580e404775f871ff74f57c22fb432449b946e5395e3778b25621a

data/lib/huginn_acumen_product_agent.rb

@@ -1,6 +1,14 @@
 require 'huginn_agent'
 
-HuginnAgent.load 'huginn_acumen_product_agent/concerns/acumen_product_query_concern'
+HuginnAgent.load 'huginn_acumen_product_agent/concerns/acumen_query_concern'
+HuginnAgent.load 'huginn_acumen_product_agent/concerns/alternate_products_query_concern'
+HuginnAgent.load 'huginn_acumen_product_agent/concerns/inv_product_query_concern'
+HuginnAgent.load 'huginn_acumen_product_agent/concerns/inv_status_query_concern'
+HuginnAgent.load 'huginn_acumen_product_agent/concerns/prod_mkt_query_concern'
+HuginnAgent.load 'huginn_acumen_product_agent/concerns/product_categories_query_concern'
+HuginnAgent.load 'huginn_acumen_product_agent/concerns/product_contributors_query_concern'
+
 HuginnAgent.load 'huginn_acumen_product_agent/acumen_client'
+HuginnAgent.load 'huginn_acumen_product_agent/acumen_agent_error'
 
 HuginnAgent.register 'huginn_acumen_product_agent/acumen_product_agent'

data/lib/huginn_acumen_product_agent/acumen_agent_error.rb

@@ -0,0 +1,10 @@
+class AcumenAgentError < StandardError
+  attr_reader :scope, :data, :original_error
+
+  def initialize(scope, message, data, original_error)
+    @scope = scope
+    @data = data
+    @original_error = original_error
+    super(message)
+  end
+end

data/lib/huginn_acumen_product_agent/acumen_client.rb

@@ -19,6 +19,12 @@ class AcumenClient
       get_results(response, 'ProdMkt')
   end
 
+  def get_inv_status(skus)
+      body = build_inv_status_query(skus)
+      response = execute_in_list_query(body, {})
+      get_results(response, 'Inv_Status')
+  end
+
   def get_linked_products(ids)
       body = build_linked_product_query(ids)
       response = execute_in_list_query(body, {})
@@ -97,6 +103,8 @@ class AcumenClient
                   <column_name>Inv_Product.BO_Reason</column_name>
                   <column_name>Inv_Product.Not_On_Website</column_name>
                   <column_name>Inv_Product.Not_Active</column_name>
+                  <column_name>Inv_Product.Disable_Web_Purchase</column_name>
+                  <column_name>Inv_Product.No_Backorder_Fill</column_name>
               </requested_output>
           </acusoapRequest>
       XML
@@ -151,6 +159,28 @@ class AcumenClient
       XML
   end
 
+  def build_inv_status_query(skus)
+      <<~XML
+          <acusoapRequest>
+              #{build_acumen_query_auth()}
+              <query>
+                <statement>
+                  <column_name>Inv_Status.ProdCode</column_name>
+                  <comparator>in</comparator>
+                  <value>#{skus.join(',')}</value>
+                </statement>
+              </query>
+              <requested_output>
+                <view_owner_table_name>Inv_Status</view_owner_table_name>
+                <view_name>Inv_StatusAllRead</view_name>
+                  <column_name>Inv_Status.Warehouse</column_name>
+                  <column_name>Inv_Status.ProdCode</column_name>
+                  <column_name>Inv_Status.Available</column_name>
+              </requested_output>
+          </acusoapRequest>
+      XML
+  end
+
   def build_product_ids_since_request(since)
       <<~XML
           <acusoapRequest>

data/lib/huginn_acumen_product_agent/acumen_product_agent.rb

@@ -3,7 +3,12 @@
 module Agents
     class AcumenProductAgent < Agent
         include WebRequestConcern
-        include AcumenProductQueryConcern
+        include AcumenQueryConcern
+        include InvProductQueryConcern
+        include ProdMktQueryConcern
+        include ProductContributorsQueryConcern
+        include ProductCategoriesQueryConcern
+        include AlternateProductsQueryConcern
 
         default_schedule '12h'
 
@@ -11,27 +16,86 @@ module Agents
         default_schedule 'never'
 
         description <<-MD
-      Huginn agent for retrieving sane ACUMEN product data.
+        Huginn agent for retrieving sane ACUMEN product data.
 
-      ## Agent Options
-      The following outlines the available options in this agent
+        ## Agent Options
+        The following outlines the available options in this agent
 
-      ### Acumen Connection
-      * endpoint: The root URL for the Acumen API
-      * site_code: The site code from Acumen
-      * password: The Acumen API password
+        ### Acumen Connection
+        * endpoint: The root URL for the Acumen API
+        * site_code: The site code from Acumen
+        * password: The Acumen API password
 
-      ### Variant Settings
-      * physical_formats: A list of the formats associated with a physical product
-      * digital_formats: A list of the formats associated with a digital product
+        ### Format Options
+        * digital_formats: A list of the formats associated with a digital product
 
-      ### Product Attributes
-      * attribute_to_property: An optional map linking Acumen attributes to Schema.org
-        product properties.
+        ### Product Attributes
+        * attribute_to_property: An optional map linking Acumen attributes to Schema.org
+          product properties.
 
-      ### Other Options
-      * ignore_skus: An optional array of Acumen product skus that will be intentionally
-        excluded from any output.
+        ### Other Options
+        * ignore_skus: An optional array of Acumen product skus that will be intentionally
+          excluded from any output.
+
+        ### Event Output
+        This agent will output one of two event types during processing:
+
+        *  Product bundles
+        *  Processing Errors
+
+        The product bundle payload will be structured as:
+
+        ```
+        {
+          products: [ { ... }, { ... }, ... ],
+          status: 200
+        }
+        ```
+
+        The processing error payload will be structured as:
+
+        ```
+        {
+          status: 500,
+          scope: '[Process Name]',
+          message: '[Error Message]',
+          data: { ... },
+          trace: [ ... ]
+        }
+        ```
+
+        ### Payload Status
+
+        `status: 200`: Indicates a true success. The agent has output the full
+        range of expected data.
+
+        `status: 206`: Indicates a partial success. The products within the bundle
+        are vaild, but the bundle _may_ be missing products that were somehow invalid.
+
+        `status: 500`: Indicates a processing error. This may represent a complete
+        process failure, but may also be issued in parallel to a `202` payload.
+
+        Because this agent receives an array of Product IDs as input, errors will be issued in
+        such a way that product processing can recover when possible. Errors that occur within
+        a specific product bundle will emit an error event, but the agent will then move
+        forward processing the next bundle.
+
+        For example, if this agent receives two products as input (`A` and `B`), and we fail to
+        load the Inv_Product record for product `A`, the agent would emit an error payload of:
+
+        ```
+        {
+          status: 500,
+          scope: 'Fetch Inv_Product Data',
+          message: 'Failed to lookup Inv_Product record for Product A',
+          data: { product_id: 123 },
+          trace: [ ... ]
+        }
+        ```
+
+        The goal of this approach is to ensure the agent outputs as much data as reasonably possible
+        with each execution. If there is an error in the Paperback version of a title, that shouldn't
+        prevent this agent from returning the Hardcover version.
 
         MD
 
@@ -40,7 +104,6 @@ module Agents
                 'endpoint' => 'https://example.com',
                 'site_code' => '',
                 'password' => '',
-                'physical_formats' => [],
                 'digital_formats' => [],
                 'attribute_to_property' => {},
             }
@@ -59,10 +122,6 @@ module Agents
                 errors.add(:base, 'password is a required field')
             end
 
-            unless options['physical_formats'].present?
-                errors.add(:base, "physical_formats is a required field")
-            end
-
             unless options['digital_formats'].present?
                 errors.add(:base, "digital_formats is a required field")
             end
@@ -72,9 +131,9 @@ module Agents
             end
 
             if options['ignore_skus']
-              unless options['ignore_skus'].is_a?(Array)
-                  errors.add(:base, "if provided, ignore_skus must be an array")
-              end
+                unless options['ignore_skus'].is_a?(Array)
+                    errors.add(:base, "if provided, ignore_skus must be an array")
+                end
             end
         end
 
@@ -95,13 +154,14 @@ module Agents
         private
 
         def handle(event)
+            # Process agent options
             endpoint = interpolated['endpoint']
             site_code = interpolated['site_code']
             password = interpolated['password']
-            physical_formats = interpolated['physical_formats']
             digital_formats = interpolated['digital_formats']
-            ignore_skus = interpolated['ignore_skus'] ? interpolated['ignore_skus'] : []
+            ignored_skus = interpolated['ignore_skus'] ? interpolated['ignore_skus'] : []
 
+            # Configure the Acumen Client
             auth = {
                 'site_code' => site_code,
                 'password' => password,
@@ -110,32 +170,74 @@ module Agents
             client = AcumenClient.new(faraday, auth)
 
             ids = event.payload['ids']
-            products = get_products_by_ids(client, ids)
-            products = get_product_variants(client, products, physical_formats, digital_formats)
-            products = get_product_categories(client, products)
-            products = get_product_contributors(client, products)
 
-            # map attributes
-            products.map do |product|
-                map_attributes(product)
+            # Load Products
+            fetch_product_bundles(client, ids, digital_formats, ignored_skus)
+        end
 
-                product['model'].each do |model|
-                    map_attributes(model)
-                end
+        private
 
-                product
-            end
+        # Returns an array of Product objects for the provided product_ids.
+        # Each object is a merged representation of all the individual Acumen tables
+        # that make up a product record with fields mapped to the schema.org/Product
+        # object definition.
+        def fetch_products(acumen_client, product_ids, digital_format_list)
+            products = fetch_inv_product_data(acumen_client, product_ids, digital_format_list)
+            products = fetch_product_marketing(acumen_client, products)
+            products = fetch_inv_status(acumen_client, products)
+            products = fetch_product_contributors(acumen_client, products)
+            products = fetch_product_categories(acumen_client, products)
 
             products.each do |product|
-                unless ignore_skus.include?(product['sku'])
-                  create_event payload: product
-                end
+                map_attributes(product)
+                update_availability(product)
             end
+
+            return products
         end
 
-        private
+        # Loads product bundles for the provided `product_ids` array and emits
+        # a unique event payload for each bundle. Emitted events will contain an
+        # array of all the product definitions for each format of a given title.
+        #
+        # NOTE: The generated bundles will contain both active and inactive products
+        # to facilitate product deletion in external systems.
+        def fetch_product_bundles(acumen_client, product_ids, digital_format_list, ignored_skus)
+
+          begin
+            data = fetch_alternate_format_ids(acumen_client, product_ids)
+            full_id_set = data[:id_set]
+            alternate_ids_map = data[:alternate_ids_map]
+            product_data = fetch_products(acumen_client, full_id_set, digital_format_list)
+
+            bundles = product_ids.map do |id|
+              bundle_ids = alternate_ids_map[id]
+              bundle_ids.append(id) unless bundle_ids.include?(id)
+              bundle_ids.sort()
+
+              bundle = []
+              bundle_ids.each() do |b_id|
+                # Filter out any products that are explicitly ignored by SKU
+                product = product_data.find { |p| p['identifier'] == b_id.to_s }
+                bundle << product unless product.nil? || ignored_skus.include?(product['sku'])
+                # NOTE: The product.nil? check is designed to handle cases where a product link
+                # points to a non existent product. Conventionally this shouldn't happen, but
+                # we've seen it, and need to account for it.
+              end
+
+              create_event payload: { products: bundle, status: 200 }
+            end
+          rescue AcumenAgentError => e
+            issue_error(e)
+          end
+        end
 
+        # Maps additional Acumen attributes to the `additionalProperty` array
+        # NOTE:  Attributes mapped in this way will be _removed_ from the
+        # `acumenAttributes` array.
         def map_attributes(product)
+
+
             attribute_to_property = interpolated['attribute_to_property']
             attributes = product['acumenAttributes']
 
@@ -152,5 +254,23 @@ module Agents
                 end
             end
         end
+
+        def update_availability(product)
+            stock_quantity = product['acumenAttributes']['stock_quantity']
+            publication_date = product['datePublished']
+            no_backorder_fill = product['noBackorderFill']
+            stock_quantity = stock_quantity.present? ? stock_quantity.to_i : 0
+
+            if (!product['isDigital'] && product['productAvailability'] == 'available')
+                if ((publication_date && publication_date.to_datetime > DateTime.current().end_of_day) || (!no_backorder_fill && stock_quantity < 1))
+                    product['productAvailability'] = 'preorder'
+                end
+                
+                if (no_backorder_fill && stock_quantity < 1)
+                    product['productAvailability'] = 'not available'
+                end
+            end
+        end
+
     end
 end

data/lib/huginn_acumen_product_agent/concerns/acumen_query_concern.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# This module contains the baseline utility methods used in the more specific
+# data concerns
+module AcumenQueryConcern
+  extend ActiveSupport::Concern
+
+  UNIT_MAP = {
+    'oz.' => 'OZ',
+    'Inches (US)' => 'INH',
+  }
+
+  protected
+
+  # Maps Acumen XML data to a hash object as specified in the provided `field_map`
+  # The field map is a hash of { source_field: target_field }
+  def response_mapper(data, field_map)
+    result = {}
+
+    field_map.each do |source_field, target_field|
+      result[target_field] = get_field_value(data, source_field)
+    end
+
+    return result
+  end
+
+  # Utility function to retrieve a value from an XML field
+  def get_field_value(data, field_name)
+    data[field_name]['__content__'] if data[field_name]
+  end
+
+  # Returns a quantitative field value (e.g. weight) as a Schema.org/QuantitativeValue
+  # object
+  def get_quantitative_value(value, unit)
+    {
+      '@type' => 'QuantitativeValue',
+      'value' => value,
+      'unitText' => unit,
+      'unitCode' => (UNIT_MAP[unit] if unit),
+    } if value
+  end
+
+  # Emits an error payload event to facilitate better debugging/logging
+  # NOTE: The `error` here is expected to be an instance of AcumenAgentError
+  def issue_error(error, status = 500)
+    # NOTE: Status is intentionally included on the top-level payload so that other
+    # agents can look for a `payload[:status]` of either 200 or 500 to distinguish
+    # between success and failure states
+    create_event payload: {
+      status: status,
+      scope: error.scope,
+      message: error.message,
+      original_error: error.original_error,
+      data: error.data,
+      trace: error.original_error.backtrace,
+    }
+  end
+end

data/lib/huginn_acumen_product_agent/concerns/agent_error_concern.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module AgentErrorConcern
+  extend ActiveSupport::Concern
+
+  def issue_error(error, status = 500)
+    # NOTE: Status is intentionally included on the top-level payload so that other
+    # agents can look for a `payload[:status]` of either 200 or 500 to distinguish
+    # between success and failure states
+    create_event payload: {
+      status: status,
+      scope: error.scope,
+      message: error.message,
+      original_error: error.original_error,
+      data: error.data,
+      trace: error.original_error.backtrace,
+    }
+  end
+end