gs1 0.1.0

data/lib/gs1/barcode/definitions.rb

@@ -0,0 +1,26 @@
+module GS1
+  module Barcode
+    # Module for handling definitions.
+    #
+    module Definitions
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      # Adding defintion class methods.
+      #
+      module ClassMethods
+        attr_reader :records
+
+        def define_records(*records)
+          @records ||= []
+          @records = records
+
+          records.each do |record|
+            attr_reader record.underscore_name
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gs1/barcode/healthcare.rb

@@ -0,0 +1,53 @@
+module GS1
+  module Barcode
+    # Barcode for boxes in healthcare business.
+    #
+    class Healthcare < Base
+      define_records GTIN, ExpirationDate, Batch, SerialNumber
+
+      def to_s(level: AIDCMarketingLevels::ENHANCED)
+        return unless valid?(level: level)
+
+        [gtin.to_ai,
+         expiration_date&.to_ai,
+         batch&.to_ai,
+         serial_number&.to_ai].compact.join
+      end
+
+      def valid?(level: AIDCMarketingLevels::ENHANCED)
+        return false unless AIDCMarketingLevels::ALL.include?(level)
+
+        validate(level)
+
+        errors.empty?
+      end
+
+      private
+
+      def validate(level)
+        errors.clear
+
+        validate_minimum
+        return if level == AIDCMarketingLevels::MINIMUM
+
+        validate_enhanced
+        return if level == AIDCMarketingLevels::ENHANCED
+
+        validate_highest
+      end
+
+      def validate_minimum
+        errors << 'Invalid gtin' unless gtin.valid?
+      end
+
+      def validate_enhanced
+        errors << 'Invalid batch' unless batch&.valid?
+        errors << 'Invalid expiration date' unless expiration_date&.valid?
+      end
+
+      def validate_highest
+        errors << 'Invalid serial number' unless serial_number&.valid?
+      end
+    end
+  end
+end

data/lib/gs1/barcode.rb

@@ -0,0 +1,4 @@
+require 'gs1/barcode/definitions'
+
+require 'gs1/barcode/base'
+require 'gs1/barcode/healthcare'

data/lib/gs1/batch.rb

@@ -0,0 +1,33 @@
+module GS1
+  # Batch or lot number: AI (10)
+  #
+  # The GS1 Application Identifier (10) indicates that the GS1 Application Identifier data field contains a
+  # batch or lot number. The batch or lot number associates an item with information the manufacturer
+  # considers relevant for traceability of the trade item to which the element string is applied. The data may
+  # refer to the trade item itself or to items contained. The number may be, for example, a production lot
+  # number, a shift number, a machine number, a time, or an internal production code. The data is
+  # alphanumeric and may include all characters contained in figure 7.11-1.
+  #
+  # Note: The batch or lot number is not part of the unique identification of a trade item.
+  #
+  #                           Figure 3.4.1-1. Format of the element string
+  #                  |----|------------------------------------------------------|
+  #                  | AI |                 Batch or lot number                  |
+  #                  |----|------------------------------------------------------|
+  #                  | 10 | X1 -------------> variable length -------------> X20 |
+  #                  |----|------------------------------------------------------|
+  #
+  # The data transmitted by the barcode reader means that the element string denoting a batch or lot
+  # number has been captured. As this element string is an attribute of a particular item, it must be
+  # processed together with the GTIN of the trade item to which it relates. When indicating this element
+  # string in the non-HRI text section of a barcode label, the following data title SHOULD be used (see
+  # also section 3.2): BATCH/LOT
+  #
+  # Source: https://www.gs1.org/sites/default/files/docs/barcodes/GS1_General_Specifications.pdf
+  #
+  class Batch < Record
+    AI = AI::BATCH_LOT
+
+    define :length, allowed: 1..20
+  end
+end

data/lib/gs1/check_digit_calculator.rb

@@ -0,0 +1,49 @@
+module GS1
+  # GS1 check digit calculation
+  #
+  # Implementation of: http://www.gs1.org/how-calculate-check-digit-manually
+  # Notice! This class does not validate the format of the given sequence,
+  # only the length.
+  #
+  class CheckDigitCalculator
+    MULTIPLIER_ARRAY = [3, 1] * 9
+    VALID_LENGTHS = [7, 11, 12, 13, 17].freeze
+
+    def initialize(sequence)
+      @sequence = sequence
+      @reverse_sequence = sequence.chars.reverse
+
+      raise ArgumentError, 'Invalid length' unless VALID_LENGTHS.include?(sequence.size)
+    end
+
+    def self.from_sequence(sequence)
+      new(sequence).check_digit
+    end
+
+    def self.with_sequence(sequence)
+      new(sequence).calculate_sequence_with_digit
+    end
+
+    def check_digit
+      sub_from_nearest_higher_ten.to_s
+    end
+
+    def calculate_sequence_with_digit
+      sequence + check_digit
+    end
+
+    private
+
+    attr_reader :sequence, :reverse_sequence
+
+    def multiplied_sequence
+      @multiplied_sequence ||= reverse_sequence.each_with_index.map do |digit, idx|
+        digit.to_i * MULTIPLIER_ARRAY[idx]
+      end
+    end
+
+    def sub_from_nearest_higher_ten
+      (10 - (multiplied_sequence.inject(:+) % 10)) % 10
+    end
+  end
+end

data/lib/gs1/content.rb

@@ -0,0 +1,47 @@
+module GS1
+  # Identification of trade items contained in a logistic unit: AI (02)
+  #
+  # The GS1 Application Identifier (02) indicates that the GS1 Application Identifier data field includes
+  # the GTIN of the contained trade items. The GTIN is used to identify trade items (see section 4).
+  #
+  # The GTIN for trade items may be a GTIN-8, GTIN-12, GTIN-13 or a GTIN-14. See section 2 for the
+  # rules for GTIN formats and mandatory or optional attributes in the various trade item applications.
+  #
+  # The GTIN of the trade items contained is the GTIN of the highest level of trade item contained in the
+  # logistic unit.
+  #
+  # Note: This element string SHALL be used only on a logistic unit if:
+  #
+  # - the logistic unit is not itself a trade item; and
+  # - all trade items that are contained at the highest level have the same GTIN
+  #
+  # The check digit is explained in section 7.9. Its verification, which must be carried out in the
+  # application software, ensures that the number is correctly composed.
+  #
+  #                           Figure 3.3.3-1. Format of the element string
+  #               |----|-------------------------------------------------------------|
+  #               |    |               Global Trade Item Number (GTIN)               |
+  #               |    |-----------------------------------------------------|-------|
+  #               | AI | GS1-8 Prefix or GS1 Company Prefix   Item reference | Check |
+  #               |    | ----------------------------->    <-----------------| digit |
+  #               |----|-----------------------------------------------------|-------|
+  #       GTIN-8  | 02 | 0   0   0   0   0   0   N1  N2  N3  N4  N5  N6  N7  |  N8   |
+  #       GTIN-12 | 02 | 0   0   N1  N2  N3  N4  N5  N6  N7  N8  N9  N10 N11 |  N12  |
+  #       GTIN-13 | 02 | 0   N1  N2  N3  N4  N5  N6  N7  N8  N9  N10 N11 N12 |  N13  |
+  #       GTIN-14 | 02 | N1  N2  N3  N4  N5  N6  N7  N8  N9  N10 N11 N12 N13 |  N14  |
+  #               |----|-----------------------------------------------------|-------|
+  #
+  # The data transmitted from the barcode reader means that the element string denoting the GTIN of
+  # trade items contained in a logistic unit has been captured. This element string must be processed
+  # together with the count of trade items, AI (37), which must appear on the same unit (see section
+  # 3.6.5). When indicating this element string in the non-HRI text section of a barcode label, the
+  # following data title SHOULD be used (see also section 3.2): CONTENT
+  #
+  # Source: https://www.gs1.org/sites/default/files/docs/barcodes/GS1_General_Specifications.pdf
+  #
+  class Content < Record
+    include Extensions::GTIN
+
+    AI = AI::CONTENT
+  end
+end

data/lib/gs1/definitions.rb

@@ -0,0 +1,79 @@
+module GS1
+  # Module for handling definitions.
+  #
+  module Definitions
+    class UnknownDefinition < StandardError; end
+
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    # Adding defintion class methods.
+    #
+    module ClassMethods
+      attr_reader :definitions
+
+      DEFINITIONS = %i[check_digit date length].freeze
+
+      def define(key, options = {})
+        raise UnknownDefinition, "#{key} is not a valid definition" unless DEFINITIONS.include?(key)
+
+        @definitions ||= {}
+
+        definitions[key] = send("normalize_#{key}_options", options)
+      end
+
+      # Currently no support for options.
+      def normalize_check_digit_options(_options)
+        {}
+      end
+
+      # Currently no support for options.
+      def normalize_date_options(_options)
+        {}
+      end
+
+      # Defaults barcode length to allowed length if not explicitly defined, only
+      # if there is one significant allowed.
+      def normalize_length_options(options)
+        options[:allowed] = normalize_multiple_option(options[:allowed])
+        options[:barcode] = normalize_singlural_option(options[:barcode])
+        options[:max_barcode] = normalize_singlural_option(options[:barcode] || options[:allowed])
+
+        options
+      end
+
+      def normalize_multiple_option(option_value)
+        case option_value
+        when nil then nil
+        when Range then option_value.to_a
+        when Array then option_value
+        else [option_value]
+        end
+      end
+
+      def normalize_singlural_option(option_value)
+        case option_value
+        when Array then option_value.last
+        else option_value
+        end
+      end
+
+      def barcode_length
+        lengths[:barcode]
+      end
+
+      def barcode_max_length
+        lengths[:max_barcode]
+      end
+
+      def allowed_lengths
+        lengths[:allowed]
+      end
+
+      def lengths
+        definitions[:length]
+      end
+    end
+  end
+end

data/lib/gs1/expiration_date.rb

@@ -0,0 +1,55 @@
+module GS1
+  # Expiration date: AI (17)
+  #
+  # The GS1 Application Identifier (17) indicates that the GS1 Application Identifier data fields contain
+  # an expiration date. The expiration date is the date that determines the limit of consumption or use
+  # of a product/coupon. Its meaning is determined based on the trade item context (e.g., for food, the
+  # date will indicate the possibility of a direct health risk resulting from use of the product after the
+  # date, for pharmaceutical products, it will indicate the possibility of an indirect health risk resulting
+  # from the ineffectiveness of the product after the date). It is often referred to as "use by date" or
+  # "maximum durability date."
+  #
+  # Note: A retailer may use this to determine a date that after which, they will no longer
+  # merchandise the product. Currently, there are implementations of best before date which are
+  # interpreted in their processes as date to Sell By.
+  #
+  # The structure is:
+  #
+  # - Year: the tens and units of the year (e.g., 2003 = 03), which is mandatory.
+  # - Month: the number of the month (e.g., January = 01), which is mandatory.
+  # - Day: the number of the day of the relevant month (e.g., second day = 02); if it is not necessary
+  # to specify the day, the field must be filled with two zeros.
+  #
+  # Note: When it is not necessary to specify the day (the Day field is filled with two zeros), the
+  # resultant data string SHALL be interpreted as the last day of the noted month including any
+  # adjustment for leap years (e.g., "130200" is "2013 February 28", "160200" is "2016 February
+  # 29", etc.).
+  #
+  # Note: This element string can only specify dates ranging from 49 years in the past to 50
+  # years in the future. Determination of the correct century is explained in section 7.12.
+  #
+  #                          Figure 3.4.5-1. Format of the element string
+  #                           |----|-----------------------------------|
+  #                           |    |          Best before date         |
+  #                           |    |-----------|-----------|-----------|
+  #                           | AI |   Year    |   Month   |    Day    |
+  #                           |    |           |           |           |
+  #                           |----|-----------|-----------|-----------|
+  #                           | 15 |   N1 N2   |   N3 N4   |   N5 N6   |
+  #                           |----|-----------|-----------|-----------|
+  #
+  # The data transmitted from the barcode reader means that the element string denoting a best before
+  # date has been captured. As this element string is an attribute of a trade item, it must be processed
+  # together with the GTIN of the trade item to which it relates.
+  #
+  # When indicating this element string in the non-HRI text section of a barcode label, the following data
+  # title SHOULD be used (see also section 3.2): BEST BEFORE or BEST BY
+  #
+  # Source: https://www.gs1.org/sites/default/files/docs/barcodes/GS1_General_Specifications.pdf
+  #
+  class ExpirationDate < Record
+    include Extensions::Date
+
+    AI = AI::USE_BY
+  end
+end

data/lib/gs1/extensions/date.rb

@@ -0,0 +1,26 @@
+require 'date'
+
+module GS1
+  module Extensions
+    # Extension for a GS1 date. Ensures correct formating and validation.
+    #
+    module Date
+      def self.included(base)
+        base.define :date
+        base.define :length, barcode: 6
+      end
+
+      def to_s
+        return data.strftime('%y%m%d') if data.is_a?(::Date)
+
+        data
+      end
+
+      def to_date
+        return data if data.is_a?(::Date)
+
+        ::Date.parse(data)
+      end
+    end
+  end
+end

data/lib/gs1/extensions/gtin.rb

@@ -0,0 +1,23 @@
+module GS1
+  module Extensions
+    # Extension for a GS1 GTIN. Ensures correct formating and validation.
+    #
+    module GTIN
+      def self.included(base)
+        base.define :check_digit
+        base.define :length, allowed: [8, 12, 13, 14].freeze, barcode: 14
+
+        base.allowed_lengths.each do |length|
+          define_method "to_gtin_#{length}" do
+            data.to_s.rjust(length, '0')
+          end
+        end
+      end
+
+      # Default to GTIN-14 since it is the most common format.
+      def to_s
+        to_gtin_14
+      end
+    end
+  end
+end

data/lib/gs1/extensions.rb

@@ -0,0 +1,2 @@
+require 'gs1/extensions/date'
+require 'gs1/extensions/gtin'

data/lib/gs1/gtin.rb

@@ -0,0 +1,39 @@
+module GS1
+  # Identification of a trade item (GTIN): AI (01)
+  #
+  # The GS1 Application Identifier (01) indicates that the GS1 Application Identifier data field contains a
+  # GTIN. The GTIN is used to identify trade items (see section 4).
+  #
+  # The GTIN for trade items may be a GTIN-8, GTIN-12, GTIN-13 or a GTIN-14. See section 2.1 for the
+  # rules for GTIN formats and mandatory or optional attributes in the various trade item applications.
+  #
+  # The check digit is explained in section 7.9. Its verification, which must be carried out in the
+  # application software, ensures that the number is correctly composed.
+  #
+  #                           Figure 3.3.2-1. Format of the element string
+  #               |----|-------------------------------------------------------------|
+  #               |    |               Global Trade Item Number (GTIN)               |
+  #               |    |-----------------------------------------------------|-------|
+  #               | AI | GS1-8 Prefix or GS1 Company Prefix   Item reference | Check |
+  #               |    | ----------------------------->    <-----------------| digit |
+  #               |----|-----------------------------------------------------|-------|
+  #       GTIN-8  | 02 | 0   0   0   0   0   0   N1  N2  N3  N4  N5  N6  N7  |  N8   |
+  #       GTIN-12 | 02 | 0   0   N1  N2  N3  N4  N5  N6  N7  N8  N9  N10 N11 |  N12  |
+  #       GTIN-13 | 02 | 0   N1  N2  N3  N4  N5  N6  N7  N8  N9  N10 N11 N12 |  N13  |
+  #       GTIN-14 | 02 | N1  N2  N3  N4  N5  N6  N7  N8  N9  N10 N11 N12 N13 |  N14  |
+  #               |----|-----------------------------------------------------|-------|
+  #
+  # The data transmitted from the barcode reader means that the element string denoting the GTIN of a
+  # fixed measure trade item has been captured.
+  #
+  # When indicating this element string in the non-HRI text section of a barcode label, the following data
+  # title SHOULD be used (see also section 3.2): GTIN
+  #
+  # Source: https://www.gs1.org/sites/default/files/docs/barcodes/GS1_General_Specifications.pdf
+  #
+  class GTIN < Record
+    include Extensions::GTIN
+
+    AI = AI::GTIN
+  end
+end

data/lib/gs1/record.rb

@@ -0,0 +1,55 @@
+module GS1
+  # Base class for a GS1 record.
+  #
+  class Record
+    include Definitions
+    include Validations
+
+    attr_reader :data
+
+    def initialize(data)
+      super
+      @data = data
+    end
+
+    singleton_class.send(:attr_reader, :descendants)
+    @descendants = []
+
+    class << self
+      def inherited(subclass)
+        descendants << subclass
+      end
+
+      def ai
+        self::AI
+      end
+
+      def underscore_name
+        name.split('::')
+            .last
+            .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+            .tr('-', '_')
+            .downcase
+            .to_sym
+      end
+    end
+
+    def ai
+      self.class.ai
+    end
+
+    def to_s
+      data&.to_s
+    end
+
+    def to_ai
+      "#{ai}#{data}"
+    end
+
+    def ==(other)
+      self.class == other.class &&
+        to_s == other.to_s
+    end
+  end
+end

data/lib/gs1/serial_number.rb

@@ -0,0 +1,31 @@
+module GS1
+  # Serial number: AI (21)
+  #
+  # The GS1 Application Identifier (21) indicates that the GS1 Application Identifier data field contains a
+  # serial number. A serial number is assigned to an entity for its lifetime. When combined with a GTIN,
+  # a serial number uniquely identifies an individual item. The serial number field is alphanumeric and
+  # may include all characters contained in figure 7.11-1. The manufacturer determines the serial
+  # number.
+  #
+  #                           Figure 3.5.2-1. Format of the element string
+  #                  |----|------------------------------------------------------|
+  #                  | AI |                    Serial number                     |
+  #                  |----|------------------------------------------------------|
+  #                  | 21 | X1 -------------> variable length -------------> X20 |
+  #                  |----|------------------------------------------------------|
+  #
+  # The data transmitted from the barcode reader means that the element string denoting a serial
+  # number has been captured. As this element string is an attribute of a trade item, it must be
+  # processed together with the GTIN of the trade item to which it relates.
+  #
+  # When indicating this element string in the non-HRI text section of a barcode label, the following data
+  # title SHOULD be used (see also section 3.2): SERIAL
+  #
+  # Source: https://www.gs1.org/sites/default/files/docs/barcodes/GS1_General_Specifications.pdf
+  #
+  class SerialNumber < Record
+    AI = AI::SERIAL
+
+    define :length, allowed: 1..20
+  end
+end

data/lib/gs1/sscc.rb

@@ -0,0 +1,43 @@
+module GS1
+  #
+  # Identification of a logistic unit (SSCC): AI (00)
+  #
+  # The GS1 Application Identifier (00) indicates that the GS1 Application Identifier data field contains an
+  # SSCC (Serial Shipping Container Code). The SSCC is used to identify logistic units (see section 2.2).
+  #
+  # The extension digit is used to increase the capacity of the serial reference within the SSCC. It is
+  # assigned by the company that constructs the SSCC. The extension digit ranges from 0-9.
+  #
+  # The GS1 Company Prefix is allocated by GS1 Member Organisations to the company that allocates
+  # the SSCC - here the physical builder or the brand owner of the logistic unit (see section 1.4.4). It
+  # makes the SSCC unique worldwide but does not identify the origin of the unit.
+  #
+  # The structure and content of the serial reference is at the discretion of owner of the GS1 Company
+  # Prefix to uniquely identify each logistic unit.
+  #
+  # The check digit is explained in section 7.9. Its verification, which must be carried out in the
+  # application software, ensures that the number is correctly composed.
+  #
+  #                           Figure 3.3.1-1. Format of the element string
+  #       |----|-----------------------------------------------------------------------------|
+  #       |    |                    SSCC (Serial Shipping Container Code)                    |
+  #       |    |-----------|---------------------------------------------------------|-------|
+  #       | AI | Extension | GS1 Company Prefix                     Serial reference | Check |
+  #       |    |   digit   | -------------->                 <-----------------------| digit |
+  #       |----|-----------|---------------------------------------------------------|-------|
+  #       | 00 |    N1     | N2 N3 N4 N5 N6 N7 N8 N9 N10 N11 N12 N13 N14 N15 N16 N17 |  N18  |
+  #       |----|-----------|---------------------------------------------------------|-------|
+  #
+  # The data transmitted from the barcode reader means that the element string denoting the SSCC of
+  # a logistic unit has been captured. When indicating this element string in the non-HRI text section of
+  # a barcode label, the following data title SHOULD be used (see also section 3.2): SSCC
+  #
+  # Source: https://www.gs1.org/sites/default/files/docs/barcodes/GS1_General_Specifications.pdf
+  #
+  class SSCC < Record
+    AI = AI::SSCC
+
+    define :check_digit
+    define :length, allowed: 18
+  end
+end

data/lib/gs1/validations/check_digit_validation.rb

@@ -0,0 +1,17 @@
+module GS1
+  module Validations
+    # Ensures correct check digit validation.
+    #
+    module CheckDigitValidation
+      def validate_check_digit
+        errors << 'Check digit mismatch' unless valid_check_digit?
+      end
+
+      def valid_check_digit?
+        GS1::CheckDigitCalculator.with_sequence(data[0..-2]) == data
+      rescue ArgumentError
+        false
+      end
+    end
+  end
+end

data/lib/gs1/validations/date_validation.rb

@@ -0,0 +1,23 @@
+require 'date'
+
+module GS1
+  module Validations
+    # Ensures correct date validation.
+    #
+    module DateValidation
+      def validate_date(_options = {})
+        errors << 'Invalid date' unless valid_date?
+      end
+
+      def valid_date?
+        return true if data.is_a?(::Date)
+
+        ::Date.parse(data)
+
+        true
+      rescue TypeError, ArgumentError
+        false
+      end
+    end
+  end
+end

data/lib/gs1/validations/length_validation.rb

@@ -0,0 +1,25 @@
+module GS1
+  module Validations
+    # Ensures correct length validation.
+    #
+    module LengthValidation
+      def validate_length
+        errors << 'Invalid length' unless valid_length?
+      end
+
+      def valid_length?
+        return false unless data
+
+        valid_barcode_length? || valid_allowed_length?
+      end
+
+      def valid_allowed_length?
+        self.class.allowed_lengths.include?(data.size)
+      end
+
+      def valid_barcode_length?
+        self.class.barcode_length == data.size if self.class.barcode_length
+      end
+    end
+  end
+end