shopify_product_taxonomy 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5cec4d780841db87dfa606e3b36510bbcb2398f03a6cf091f1a1867e0b88b8b0
-  data.tar.gz: 3142307e81c2049fedf3fcf38d7ba87bb2594b4a88185aadfb1cb7dceac6c2b3
+  metadata.gz: 68f41afc40ad1e0c0d16d45e41f105c984d6e5159621f4417ab16270ccb56af7
+  data.tar.gz: 776eb4172eef466640e468c485aa07bd6cd18bd012bc91f1dfbdca767e1ef98e
 SHA512:
-  metadata.gz: fb4fbe719cd799f493b7da19f6be9e2c12f776a136a3062a776645fb680cc96fbf4eef2add7eb6ea939c6a76b1c30af90888ce00f23e5633d71cfd571720ae35
-  data.tar.gz: 1a272445bdd6bb760cae6e4ac2538a58de1f8588a857ab291a32ab450661fde810e1c26223eeb1b28bf105dd2a2f182655fba1372d6e79ba6d0f41e6dc2374b3
+  metadata.gz: 06a00c7523ff2d8c6d5cae5f5d1d7624cebee3021e684c56852d03cd041d622a7f0af759737559a70c4d4e68885c221770f807e356ced05f6d61ac105d77c40a
+  data.tar.gz: 2f2e4747e3cfeead16b45478c5bf858869ffe3a213bca7ea22bd7b385d08f0aa3b02ca0c8a72c0199d96e3172e78164e1b93c5df2546db30f49c77eb9ae3f144

data/lib/product_taxonomy/loader.rb

@@ -5,12 +5,20 @@ require "yaml"
 module ProductTaxonomy
   class Loader
     class << self
-      def load(values_path:, attributes_path:, categories_glob:)
+      def load(data_path:)
+        ProductTaxonomy.data_path = data_path
+
         return if ProductTaxonomy::Category.all.any?
 
+        values_path = File.join(data_path, "values.yml")
+        attributes_path = File.join(data_path, "attributes.yml")
+        return_reasons_path = File.join(data_path, "return_reasons.yml")
+        categories_glob = Dir.glob(File.join(data_path, "categories", "*.yml"))
+
         begin
           ProductTaxonomy::Value.load_from_source(YAML.load_file(values_path))
           ProductTaxonomy::Attribute.load_from_source(YAML.load_file(attributes_path))
+          ProductTaxonomy::ReturnReason.load_from_source(YAML.load_file(return_reasons_path))
 
           categories_source_data = categories_glob.each_with_object([]) do |file, array|
             array.concat(YAML.safe_load_file(file))
@@ -28,4 +36,3 @@ module ProductTaxonomy
     end
   end
 end
-

data/lib/product_taxonomy/models/category.rb

@@ -22,6 +22,7 @@ module ProductTaxonomy
             id: item["id"],
             name: item["name"],
             attributes: Array(item["attributes"]).map { Attribute.find_by(friendly_id: _1) || _1 },
+            return_reasons: Array(item["return_reasons"]).map { ReturnReason.find_by(friendly_id: _1) || _1 },
           )
         end
 
@@ -37,6 +38,7 @@ module ProductTaxonomy
           node.validate!(:category_tree_loaded)
           node.children.sort_by!(&:name)
           node.attributes.sort_by!(&:name)
+          # `return_reasons` order is intentionally preserved from `data/categories/*.yml`.
           root_nodes << node if node.root?
         end
         @verticals.sort_by!(&:name)
@@ -74,6 +76,7 @@ module ProductTaxonomy
     validates :id, format: { with: /\A[a-z]{2}(-\d+)*\z/ }, on: :create
     validates :name, presence: true, on: :create
     validate :attributes_found?, on: :create
+    validate :return_reasons_found?, on: :create
     validates_with ProductTaxonomy::Indexed::UniquenessValidator, attributes: [:id], on: :create
 
     # Validations that can only be performed after the category tree has been loaded.
@@ -84,19 +87,21 @@ module ProductTaxonomy
 
     localized_attr_reader :name, keyed_by: :id
 
-    attr_reader :id, :children, :secondary_children, :attributes
+    attr_reader :id, :children, :secondary_children, :attributes, :return_reasons
     attr_accessor :parent, :secondary_parents
 
     # @param id [String] The ID of the category.
     # @param name [String] The name of the category.
     # @param attributes [Array<Attribute>] The attributes of the category.
+    # @param return_reasons [Array<ReturnReason>] The return reasons for the category.
     # @param parent [Category] The parent category of the category.
-    def initialize(id:, name:, attributes: [], parent: nil)
+    def initialize(id:, name:, attributes: [], return_reasons: [], parent: nil)
       @id = id
       @name = name
       @children = []
       @secondary_children = []
       @attributes = attributes
+      @return_reasons = return_reasons
       @parent = parent
       @secondary_parents = []
     end
@@ -134,6 +139,13 @@ module ProductTaxonomy
       @attributes << attribute
     end
 
+    # Add a return reason to the category
+    #
+    # @param [ReturnReason] return_reason
+    def add_return_reason(return_reason)
+      @return_reasons << return_reason
+    end
+
     #
     # Information
     #
@@ -286,6 +298,18 @@ module ProductTaxonomy
       end
     end
 
+    def return_reasons_found?
+      return_reasons&.each do |return_reason|
+        next if return_reason.is_a?(ReturnReason)
+
+        errors.add(
+          :return_reasons,
+          :not_found,
+          message: "not found for friendly ID \"#{return_reason}\"",
+        )
+      end
+    end
+
     def children_found?
       children&.each do |child|
         next if child.is_a?(Category)

data/lib/product_taxonomy/models/mixins/localized.rb

@@ -64,7 +64,7 @@ module ProductTaxonomy
     end
 
     def localizations_humanized_model_name
-      name.demodulize.humanize.downcase.pluralize
+      name.demodulize.underscore.pluralize
     end
   end
 end

data/lib/product_taxonomy/models/return_reason.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module ProductTaxonomy
+  class ReturnReason
+    include ActiveModel::Validations
+    include FormattedValidationErrors
+    extend Localized
+    extend Indexed
+
+    class << self
+      # Override to match folder name convention (return_reasons vs returnreasons)
+      def localizations_humanized_model_name
+        "return_reasons"
+      end
+
+      # Load return reasons from source data. By default, this data is deserialized from a YAML file in the `data` directory.
+      #
+      # @param source_data [Array<Hash>] The source data to load return reasons from.
+      # @return [void]
+      def load_from_source(source_data)
+        raise ArgumentError, "source_data must be an array" unless source_data.is_a?(Array)
+
+        source_data.each do |return_reason_data|
+          raise ArgumentError, "source_data must contain hashes" unless return_reason_data.is_a?(Hash)
+
+          return_reason = return_reason_from(return_reason_data)
+          ReturnReason.add(return_reason)
+          return_reason.validate!(:create)
+        end
+      end
+
+      # Reset all class-level state
+      def reset
+        @localizations = nil
+        @hashed_models = nil
+      end
+
+      # Get the next ID for a newly created return reason.
+      #
+      # @return [Integer] The next ID.
+      def next_id = (all.max_by(&:id)&.id || 0) + 1
+
+      private
+
+      def return_reason_from(return_reason_data)
+        ReturnReason.new(
+          id: return_reason_data["id"],
+          name: return_reason_data["name"],
+          description: return_reason_data["description"],
+          friendly_id: return_reason_data["friendly_id"],
+          handle: return_reason_data["handle"],
+        )
+      end
+    end
+
+    validates :id, presence: true, numericality: { only_integer: true }, on: :create
+    validates :name, presence: true, on: :create
+    validates :friendly_id, presence: true, on: :create
+    validates :handle, presence: true, on: :create
+    validates :description, presence: true, on: :create
+    validates_with ProductTaxonomy::Indexed::UniquenessValidator, attributes: [:friendly_id], on: :create
+
+    localized_attr_reader :name, :description
+
+    attr_reader :id, :friendly_id, :handle
+
+    # @param id [Integer] The ID of the return reason.
+    # @param name [String] The name of the return reason.
+    # @param description [String] The description of the return reason.
+    # @param friendly_id [String] The friendly ID of the return reason.
+    # @param handle [String] The handle of the return reason.
+    def initialize(id:, name:, description:, friendly_id:, handle:)
+      @id = id
+      @name = name
+      @description = description
+      @friendly_id = friendly_id
+      @handle = handle
+    end
+
+    # The global ID of the return reason
+    #
+    # @return [String]
+    def gid
+      "gid://shopify/ReturnReasonDefinition/#{id}"
+    end
+  end
+end
+

data/lib/product_taxonomy/models/serializers/category/data/data_serializer.rb

@@ -14,11 +14,20 @@ module ProductTaxonomy
             # @param [Category] category
             # @return [Hash]
             def serialize(category)
+              return_reason_ids = category.return_reasons.map(&:friendly_id)
+              has_unknown = return_reason_ids.delete('unknown')
+              has_other = return_reason_ids.delete('other')
+
+              sorted_return_reasons = AlphanumericSorter.sort(return_reason_ids)
+              sorted_return_reasons += ['unknown'] if has_unknown
+              sorted_return_reasons += ['other'] if has_other
+              
               {
                 "id" => category.id,
                 "name" => category.name,
                 "children" => category.children.sort_by(&:id_parts).map(&:id),
                 "attributes" => AlphanumericSorter.sort(category.attributes.map(&:friendly_id), other_last: true),
+                "return_reasons" => sorted_return_reasons,
               }
             end
           end

data/lib/product_taxonomy/models/serializers/category/dist/json_serializer.rb

@@ -38,6 +38,14 @@ module ProductTaxonomy
                     "extended" => attr.is_a?(ExtendedAttribute),
                   }
                 end,
+                "return_reasons" => category.return_reasons.map do |return_reason|
+                  {
+                    "id" => return_reason.gid,
+                    "name" => return_reason.name(locale:),
+                    "handle" => return_reason.handle,
+                    "description" => return_reason.description(locale:),
+                  }
+                end,
                 "children" => category.children.map do |child|
                   {
                     "id" => child.gid,

data/lib/product_taxonomy/models/serializers/category/docs/search_serializer.rb

@@ -7,7 +7,7 @@ module ProductTaxonomy
         module SearchSerializer
           class << self
             def serialize_all
-              ProductTaxonomy::Category.all_depth_first.flat_map { serialize(_1) }
+              ProductTaxonomy::Category.all_depth_first.map { serialize(_1) }
             end
 
             # @param [Category] category

data/lib/product_taxonomy/models/serializers/category/docs/siblings_serializer.rb

@@ -29,6 +29,7 @@ module ProductTaxonomy
                 "node_type" => category.root? ? "root" : "leaf",
                 "ancestor_ids" => category.ancestors.map(&:gid).join(","),
                 "attribute_handles" => category.attributes.map(&:handle).join(","),
+                "return_reason_handles" => category.return_reasons.map(&:handle).join(","),
               }
             end
           end

data/lib/product_taxonomy/models/serializers/return_reason/data/data_serializer.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module ProductTaxonomy
+  module Serializers
+    module ReturnReason
+      module Data
+        module DataSerializer
+          class << self
+            # @return [Array<Hash>] Array of serialized return data
+            def serialize_all
+              ProductTaxonomy::ReturnReason.all.sort_by(&:id).map { serialize(_1) }
+            end
+
+            # @param return_reason [ReturnReason] The return reason to serialize
+            # @return [Hash] Hash containing the return reason data
+            def serialize(return_reason)
+              {
+                "id" => return_reason.id,
+                "name" => return_reason.name,
+                "description" => return_reason.description,
+                "friendly_id" => return_reason.friendly_id,
+                "handle" => return_reason.handle,
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+
+
+

data/lib/product_taxonomy/models/serializers/return_reason/data/localizations_serializer.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ProductTaxonomy
+  module Serializers
+    module ReturnReason
+      module Data
+        class LocalizationsSerializer
+          class << self
+            # @param locale [String] The locale to use for serialization
+            # @return [Hash] Hash containing localized return reason data
+            def serialize_all(locale: "en")
+              {
+                locale => {
+                  "return_reasons" => ProductTaxonomy::ReturnReason.all.sort_by(&:friendly_id).each_with_object({}) do |return_reason, hash|
+                    hash[return_reason.friendly_id] = serialize(return_reason, locale:)
+                  end,
+                },
+              }
+            end
+
+            # @param return_reason [ReturnReason] The return reason to serialize
+            # @param locale [String] The locale to use for serialization
+            # @return [Hash] Hash containing name and description
+            def serialize(return_reason, locale: "en")
+              {
+                "name" => return_reason.name(locale:),
+                "description" => return_reason.description(locale:),
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+
+
+

data/lib/product_taxonomy/models/serializers/return_reason/dist/json_serializer.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module ProductTaxonomy
+  module Serializers
+    module ReturnReason
+      module Dist
+        class JsonSerializer
+          class << self
+            # @param return_reason [ReturnReason] The return reason to serialize
+            # @param locale [String] The locale to use for localized return reasons
+            # @return [Hash] A hash containing the serialized return reason data
+            def serialize_all(version:, locale: "en")
+              {
+                "version" => version,
+                "return_reasons" => ProductTaxonomy::ReturnReason.all.map { serialize(_1, locale:) },
+              }
+            end
+
+            # @param return_reason [ReturnReason]
+            # @param locale [String] The locale to use for localized return reasons.
+            # @return [Hash]
+            def serialize(return_reason, locale: "en")
+              {
+                "id" => return_reason.gid,
+                "name" => return_reason.name(locale:),
+                "handle" => return_reason.handle,
+                "description" => return_reason.description(locale:),
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/product_taxonomy/models/serializers/return_reason/dist/txt_serializer.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module ProductTaxonomy
+  module Serializers
+    module ReturnReason
+      module Dist
+        class TxtSerializer
+          class << self
+            # @param version [String] The version to include in the output
+            # @param locale [String] The locale to use for localized return reasons
+            # @param padding [Integer] The padding to use for the GID
+            # @return [String] The formatted text output with header and return reasons
+            def serialize_all(version:, locale: "en", padding: longest_gid_length)
+              header = <<~HEADER
+                # Shopify Product Taxonomy - Return Reasons: #{version}
+                # Format: {GID} : {Return reason name}
+
+              HEADER
+
+              return_reasons_txt = ProductTaxonomy::ReturnReason
+                .all
+                .map { serialize(_1, padding:, locale:) }
+                .join("\n")
+
+              header + return_reasons_txt
+            end
+
+            # @param return_reason [ReturnReason]
+            # @param padding [Integer] The padding to use for the GID.
+            # @param locale [String] The locale to use for localized return reasons.
+            # @return [String]
+            def serialize(return_reason, padding: 0, locale: "en")
+              "#{return_reason.gid.ljust(padding)} : #{return_reason.name(locale:)}"
+            end
+
+            private
+
+            def longest_gid_length
+              ProductTaxonomy::ReturnReason.all.map { _1.gid.length }.max || 0
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/product_taxonomy/models/serializers/return_reason/docs/base_serializer.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module ProductTaxonomy
+  module Serializers
+    module ReturnReason
+      module Docs
+        module BaseSerializer
+          class << self
+            def serialize_all
+              ProductTaxonomy::ReturnReason.all.map { serialize(_1) }
+            end
+
+            # @param [ReturnReason] return_reason
+            # @return [Hash]
+            def serialize(return_reason)
+              {
+                "id" => return_reason.gid,
+                "name" => return_reason.name,
+                "handle" => return_reason.handle,
+                "description" => return_reason.description,
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end
+

data/lib/product_taxonomy/models/serializers/return_reason/docs/reversed_serializer.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ProductTaxonomy
+  module Serializers
+    module ReturnReason
+      module Docs
+        module ReversedSerializer
+          class << self
+            def serialize_all
+              return_reasons_to_categories = ProductTaxonomy::Category.all.each_with_object({}) do |category, hash|
+                category.return_reasons.each do |return_reason|
+                  hash[return_reason] ||= []
+                  hash[return_reason] << category
+                end
+              end
+
+              serialized_return_reasons = ProductTaxonomy::ReturnReason.all.map do |return_reason|
+                serialize(return_reason, return_reasons_to_categories[return_reason])
+              end
+
+              {
+                "return_reasons" => serialized_return_reasons,
+              }
+            end
+
+            # @param [ReturnReason] return_reason The return reason to serialize.
+            # @param [Array<Category>] return_reason_categories The categories that the return reason belongs to.
+            # @return [Hash] The serialized return reason.
+            def serialize(return_reason, return_reason_categories)
+              return_reason_categories ||= []
+              {
+                "id" => return_reason.gid,
+                "handle" => return_reason.handle,
+                "name" => return_reason.name,
+                "description" => return_reason.description,
+                "categories" => return_reason_categories.sort_by(&:full_name).map do |category|
+                  {
+                    "id" => category.gid,
+                    "full_name" => category.full_name,
+                  }
+                end,
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/product_taxonomy/models/serializers/return_reason/docs/search_serializer.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ProductTaxonomy
+  module Serializers
+    module ReturnReason
+      module Docs
+        module SearchSerializer
+          class << self
+            def serialize_all
+              ProductTaxonomy::ReturnReason.all.map { serialize(_1) }
+            end
+
+            # @param [ReturnReason] return_reason
+            # @return [Hash]
+            def serialize(return_reason)
+              {
+                "searchIdentifier" => return_reason.handle,
+                "title" => return_reason.name,
+                "url" => "?returnReasonHandle=#{CGI.escapeURIComponent(return_reason.handle)}",
+                "return_reason" => {
+                  "handle" => return_reason.handle,
+                  "name" => return_reason.name,
+                  "description" => return_reason.description,
+                },
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/product_taxonomy/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module ProductTaxonomy
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end
 

data/lib/product_taxonomy.rb

@@ -26,6 +26,7 @@ require_relative "product_taxonomy/models/mixins/formatted_validation_errors"
 require_relative "product_taxonomy/models/attribute"
 require_relative "product_taxonomy/models/extended_attribute"
 require_relative "product_taxonomy/models/value"
+require_relative "product_taxonomy/models/return_reason"
 require_relative "product_taxonomy/models/category"
 require_relative "product_taxonomy/models/taxonomy"
 require_relative "product_taxonomy/models/mapping_rule"
@@ -48,3 +49,27 @@ require_relative "product_taxonomy/models/serializers/value/data/data_serializer
 require_relative "product_taxonomy/models/serializers/value/data/localizations_serializer"
 require_relative "product_taxonomy/models/serializers/value/dist/json_serializer"
 require_relative "product_taxonomy/models/serializers/value/dist/txt_serializer"
+require_relative "product_taxonomy/models/serializers/return_reason/data/data_serializer"
+require_relative "product_taxonomy/models/serializers/return_reason/data/localizations_serializer"
+require_relative "product_taxonomy/models/serializers/return_reason/docs/base_serializer"
+require_relative "product_taxonomy/models/serializers/return_reason/docs/reversed_serializer"
+require_relative "product_taxonomy/models/serializers/return_reason/docs/search_serializer"
+require_relative "product_taxonomy/models/serializers/return_reason/dist/json_serializer"
+require_relative "product_taxonomy/models/serializers/return_reason/dist/txt_serializer"
+require_relative "product_taxonomy/commands/command"
+require_relative "product_taxonomy/commands/generate_dist_command"
+require_relative "product_taxonomy/commands/find_unmapped_external_categories_command"
+require_relative "product_taxonomy/commands/generate_docs_command"
+require_relative "product_taxonomy/commands/generate_release_command"
+require_relative "product_taxonomy/commands/dump_categories_command"
+require_relative "product_taxonomy/commands/dump_attributes_command"
+require_relative "product_taxonomy/commands/dump_values_command"
+require_relative "product_taxonomy/commands/dump_return_reasons_command"
+require_relative "product_taxonomy/commands/dump_integration_full_names_command"
+require_relative "product_taxonomy/commands/sync_en_localizations_command"
+require_relative "product_taxonomy/commands/add_category_command"
+require_relative "product_taxonomy/commands/add_attribute_command"
+require_relative "product_taxonomy/commands/add_attributes_to_categories_command"
+require_relative "product_taxonomy/commands/add_value_command"
+require_relative "product_taxonomy/commands/add_return_reason_command"
+require_relative "product_taxonomy/commands/add_return_reasons_to_categories_command"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shopify_product_taxonomy
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Shopify
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-11-27 00:00:00.000000000 Z
+date: 2026-02-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -74,6 +74,7 @@ files:
 - lib/product_taxonomy/models/mixins/formatted_validation_errors.rb
 - lib/product_taxonomy/models/mixins/indexed.rb
 - lib/product_taxonomy/models/mixins/localized.rb
+- lib/product_taxonomy/models/return_reason.rb
 - lib/product_taxonomy/models/serializers/attribute/data/data_serializer.rb
 - lib/product_taxonomy/models/serializers/attribute/data/localizations_serializer.rb
 - lib/product_taxonomy/models/serializers/attribute/dist/json_serializer.rb
@@ -88,6 +89,13 @@ files:
 - lib/product_taxonomy/models/serializers/category/dist/txt_serializer.rb
 - lib/product_taxonomy/models/serializers/category/docs/search_serializer.rb
 - lib/product_taxonomy/models/serializers/category/docs/siblings_serializer.rb
+- lib/product_taxonomy/models/serializers/return_reason/data/data_serializer.rb
+- lib/product_taxonomy/models/serializers/return_reason/data/localizations_serializer.rb
+- lib/product_taxonomy/models/serializers/return_reason/dist/json_serializer.rb
+- lib/product_taxonomy/models/serializers/return_reason/dist/txt_serializer.rb
+- lib/product_taxonomy/models/serializers/return_reason/docs/base_serializer.rb
+- lib/product_taxonomy/models/serializers/return_reason/docs/reversed_serializer.rb
+- lib/product_taxonomy/models/serializers/return_reason/docs/search_serializer.rb
 - lib/product_taxonomy/models/serializers/value/data/data_serializer.rb
 - lib/product_taxonomy/models/serializers/value/data/localizations_serializer.rb
 - lib/product_taxonomy/models/serializers/value/dist/json_serializer.rb