gobl 0.1.2

data/lib/gobl/num/amount.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+module GOBL
+  module Num
+    # Represents a numeric quantity with optional decimal places that determine accuracy
+    class Amount
+      # The integer value of the amount
+      attr_reader :value
+
+      # The exponent, or number of significant figures of the amount
+      attr_reader :exp
+
+      # Creates a new {Amount} from the given data object
+      #
+      # @param data [Hash, String, #to_s, Amount] the data object. Supported types:
+      #
+      #   * A `Hash` with a `:value` key and, optionally, an `:exp` one,
+      #   * A `String` or any other object that can be coerced into one via `#to_s`,
+      #   * Another {Amount}
+      def initialize(data)
+        if data.is_a?(String)
+          parse(data)
+        elsif data.is_a?(Hash)
+          @value = data[:value]
+          @exp = data[:exp] || 0
+        elsif data.is_a?(self.class)
+          @value = data.value
+          @exp = data.exp
+        elsif data.respond_to?(:to_s)
+          parse(data.to_s)
+        else
+          raise 'Unsupported input amount'
+        end
+      end
+
+      # Creates a new {Amount} from a GOBL value
+      #
+      # @param data [Hash] a GOBL value
+      #
+      # @return [Amount] the object created from the given data
+      def self.from_gobl!(data)
+        new(data)
+      end
+
+      # Deserializes an {Amount} from a JSON string
+      #
+      # @param json [String] a JSON string
+      #
+      # @return [Amount] the deserialized {Amount}
+      def self.from_json!(json)
+        from_gobl!(JSON.parse(json))
+      end
+
+      # Returns a GOBL value representing the current amount
+      #
+      # @return [String] the GOBL value that represents the current amount
+      def to_gobl
+        to_s
+      end
+
+      # Serializes a GOBL struct into a JSON string
+      #
+      # @param options [#to_h] a Hash-like object to pass to `JSON.generate`
+      #
+      # @return [GOBL::Struct] the JSON string representing the GOBL struct
+      def to_json(options = nil)
+        JSON.generate(to_gobl, options)
+      end
+
+      # Returns the string representation of the current amount
+      #
+      # @return [String] the string representation of the current amount
+      #
+      # @see #as_s
+      def to_s
+        as_s
+      end
+
+      # Returns the string representation of the current amount
+      #
+      # @return [String] the string representation of the current amount
+      def as_s
+        return value.to_s if exp.zero?
+        raise 'exponent too high' if exp > 100
+
+        p = 10**exp
+        v1 = value / p
+        v2 = value - (v1 * p)
+        v2 = -v2 if v2.negative?
+        format('%d.%0*d', v1, exp, v2)
+      end
+
+      # Rescales each {Amount} in the pair ensuring both have the same exponent
+      #
+      # @param a1 [Amount] the first amount of the pair
+      # @param a2 [Amount] the second amount of the pair
+      #
+      # @return [Array(Amount, Amount)] the rescaled pair of amounts
+      def self.rescale_pair(a1, a2)
+        exp = a1.exp
+        exp = a2.exp if a2.exp > exp
+        [a1.rescale(exp), a2.rescale(exp)]
+      end
+
+      # Compares the current amount with another one
+      #
+      # @param other [Amount] the {Amount} to compare with
+      #
+      # @return [Integer] the result of the comparison:
+      #
+      #   * `-1` if the current amount is lesser than the given one
+      #   * `1` if current amount is greater than the given one
+      #   * `0` if both amounts are equal
+      def compare(other)
+        a1, a2 = self.class.rescale_pair(self, other)
+        if a1.value < a2.value
+          -1
+        elsif a1.value > a2.value
+          1
+        else
+          0 # same
+        end
+      end
+
+      # Returns whether the current amount is equal to another one
+      #
+      # @param other [Amount] the {Amount} to compare with
+      #
+      # @return [Boolean] whether the two amounts are equal (`true`) or not (`false`)
+      def ==(other)
+        compare(other).zero?
+      end
+
+      # Changes the exponent of the {Amount} multipling or dividing its value as
+      # necessary. A lower exponent implies loosing accuracy.
+      #
+      # @param e [Integer] the new exponent
+      #
+      # @return [Amount] the rescaled {Amount}
+      def rescale(e)
+        if exp > e
+          # divide
+          x = exp - e
+          v = (value.to_f / (10**x)).round
+          self.class.new(value: v, exp: e)
+        elsif exp < e
+          # multiply
+          x = e - exp
+          v = value * (10**x)
+          self.class.new(value: v, exp: e)
+        else
+          # nothing
+          self
+        end
+      end
+
+      # Returns whether the current amount is equal to zero
+      #
+      # @return [Boolean] `true` if the current amount is equal to zero, `false`otherwise
+      def zero?
+        value.zero?
+      end
+
+      # Adds the current amount to a given one
+      #
+      # @param a2 [Amount] the amount to add
+      #
+      # @return [Amount] the amount resulted from the operation
+      def add(a2)
+        a2 = a2.rescale(exp)
+        self.class.new(value: value + a2.value, exp: exp)
+      end
+
+      # Subtracts a given {Amount} from the current one
+      #
+      # @param a2 [Amount] the amount to subtract
+      #
+      # @return [Amount] the amount resulted from the operation
+      def subtract(a2)
+        a2 = a2.rescale(exp)
+        self.class.new(value: value - a2.value, exp: exp)
+      end
+
+      # Multiplies a given {Amount} with the current one
+      #
+      # @param a2 [Amount] the amount to multiply with
+      #
+      # @return [Amount] the amount resulted from the operation
+      def multiply(a2)
+        v = (value * a2.value) / (10**a2.exp)
+        self.class.new(value: v, exp: exp)
+      end
+
+      # Divides the current amount by the given one
+      #
+      # @param a2 [Amount] the amount to divide by
+      #
+      # @return [Amount] the amount resulted from the operation
+      def divide(a2)
+        v = (value.to_f * (10**a2.exp)) / a2.value.to_f
+        self.class.new(value: v.round, exp: exp)
+      end
+
+      # Splits the current amount into equal `x` parts providing a second amount with
+      # the remainder. This is like {#divide}, but will correctly account for rounding
+      # errors.
+      #
+      # @param x [Integer] the number of parts to divide the amount into
+      #
+      # @return [Array(Amount, Amount)] the split amount and the remider amount
+      def split(x)
+        a2 = divide(self.class.new(value: x, exp: 0))
+        a3 = a2.multiply(self.class.new(value: x - 1, exp: 0))
+        a3 = subtract(a3)
+        [a2, a3]
+      end
+
+      # Inverts the sign of the current amount
+      #
+      # @return [Amount] the amount with the opposite sign
+      def invert
+        self.class.new(value: -value, exp: exp)
+      end
+
+      protected
+
+      # Extract the value and exponent from the string.
+      # Implementation copied from base GOBL library.
+      def parse(str)
+        x = str.split('.')
+        raise "invalid amount '#{str}'" if x.length > 2 # abort
+
+        v = x[0].to_i
+        e = 0
+
+        if x[1]
+          v2 = x[1].to_i
+          e = x[1].length
+          v *= 10**e
+          v += v2
+        end
+
+        @value = v
+        @exp = e
+      end
+    end
+  end
+end

data/lib/gobl/num/percentage.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module GOBL
+  module Num
+    Factor1 = Amount.new(value: 1) # @api private
+    Factor100 = Amount.new(value: 100) # @api private
+
+    # Similar to {GOBL::Num::Amount}, but specialized in representing percentages
+    class Percentage < Amount
+      # Returns a string representation of the percentage with the percentage symbol
+      #
+      # @return [String] the string representing the percentage
+      def to_s
+        "#{to_s_without_symbol}%"
+      end
+
+      # Returns a string representation of the percentage with_out the percentage symbol
+      #
+      # @return [String] the string representing the percentage
+      def to_s_without_symbol
+        e = exp - 2
+        e = 0 if e.negative?
+        p = multiply(Factor100).rescale(e)
+        p.as_s
+      end
+
+      # Calculates the "percent of" a given amount
+      #
+      # @param a [GOBL::Num::Amount] the amount to calculate the percent of
+      #
+      # @return [GOBL::Num::Amount] the calculated amount
+      def of(a)
+        a.multiply(self)
+      end
+
+      # Calculates what "percent from" the given amount would result assuming the rate has
+      # already been applied. Put otherwise, for a given amount that was increased by the
+      # current percentage, this method returns the amount of that increment.
+      #
+      # @example
+      #   original_amount = GOBL::Num::Amount.new("200")
+      #   percentage = GOBL::Num::Percentage.new("25%")
+      #   increment = percentage.of(original_amount) #=> 50
+      #
+      #   increased_amount = original_amount.add(increment) #=> 250
+      #   percentage.from(increased_amount) #=> 50
+      #
+      # @param a [GOBL::Num::Amount] the amount to calculate the percent from
+      #
+      # @return [GOBL::Num::Amount] the calculated amount
+      def from(a)
+        x = a.divide(factor)
+        a.subtract(x)
+      end
+
+      # Returns the percentage amount as a factor, adding 1 to the rate
+      #
+      # @return [GOBL::Num::Amount] the factor
+      def factor
+        Amount.new(value: value, exp: exp).add(Factor1)
+      end
+
+      protected
+
+      def parse(data)
+        return if data.length.zero?
+
+        rescale = false
+        if data[-1] == '%'
+          data = data.chomp('%')
+          rescale = true
+        end
+
+        super(data)
+
+        if rescale
+          p = self.rescale(exp + 2).divide(Factor100)
+          @value = p.value
+          @exp = p.exp
+        end
+      end
+    end
+  end
+end

data/lib/gobl/operations/service_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module GOBL
+  module Operations
+    # Wraps an error returned by the backend GOBL service when attempting to run an
+    # operation
+    class ServiceError < StandardError
+    end
+  end
+end

data/lib/gobl/operations/validation_result.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module GOBL
+  module Operations
+    # The result of a GOBL validation over a GOBL structure
+    class ValidationResult
+      SERVICE_ERROR_REGEX = /^code=(?<code>\d+), message=(?<msg>.+)$/.freeze # @api private
+
+      def initialize(errors)
+        @errors = errors
+      end
+
+      # Whether the GOBL structure were valid or not
+      #
+      # @return [Boolean]
+      def valid?
+        @errors.empty?
+      end
+
+      # The list of errors found in the GOBL structure
+      #
+      # @return [Array]
+      def errors
+        @errors || []
+      end
+
+      # Builds a new `ValidationResult` object resulted from parsing the service
+      #   error response given as a parameter
+      #
+      # @param service_error [String]
+      # @return [ValidationResult]
+      def self.from_service_error(service_error)
+        message = service_error.match(SERVICE_ERROR_REGEX)[:msg]
+        errors = message.split('; ')
+        new errors
+      end
+
+      # Builds a new `ValidationResult` object for a positive `validate` operation
+      #
+      # @return [ValidationResult]
+      def self.valid
+        new []
+      end
+    end
+  end
+end

data/lib/gobl/operations.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module GOBL
+  # Provides the API to execute operations over GOBL structures. It implements them by
+  # sending HTTP requests to the bulk endpoint of the service that the GOBL CLI makes
+  # available via the `gobl serve` command. The server's host and port must be configured
+  # using `GOBL.config.service_host` and `GOBL.config.service_port`.
+  #
+  # @example
+  #   GOBL.config.service_host = 'localhost'
+  #   GOBL.config.service_port = 8080
+  #
+  #   doc = GOBL::Document.from_gobl!(
+  #     '$schema' => 'https://gobl.org/draft-0/bill/invoice',
+  #     'code' => 'SAMPLE-001',
+  #     'currency' => 'EUR',
+  #     'issue_date' => '2022-02-01',
+  #     'supplier' => { 'tax_id' => { 'country' => 'ES', 'code' => '54387763P' }, 'name' => 'Provide One S.L.' },
+  #     'customer' => { 'tax_id' => { 'country' => 'ES', 'code' => '54387763P' }, 'name' => 'Sample Consumer' },
+  #     'lines' => [ { 'quantity' => '20', 'item' => { 'name' => 'Development services', 'price' => '90.00' } } ]
+  #   )
+  #
+  #   built_doc = GOBL.build(doc)
+  #
+  #   invoice = built_doc.extract
+  #   invoice.totals.total.to_s #=> "1800.00"
+  module Operations
+    # @api private
+    VALIDATABLE_TYPES = SIGNABLE_TYPES = BUILDABLE_TYPES = [
+      GOBL::Document,
+      GOBL::Envelope
+    ].freeze
+
+    # Calculates and validates an envelope or document, wrapping it in an envelope if
+    # requested.
+    #
+    # @param struct [GOBL::Document, GOBL::Envelope] the document or envelope to build.
+    # @param envelop [Boolean] whether the operation should envelop the document.
+    # @param draft [Boolean] whether the envelope should be flagged as a draft.
+    #
+    # @return [GOBL::Envelope, GOBL::Document] a built envelope or document.
+    #
+    # @raise [GOBL::Operations::ServiceError] if the service returns any errors.
+    #
+    # @example Build a document without enveloping it.
+    #   invoice = GOBL::Document.from_json!(File.read('invoice.json'))
+    #   GOBL.build(invoice) #=> A new, calculated `GOBL::Document`
+    #
+    # @example Build a document and wrap in a draft envelope.
+    #   invoice = GOBL::Document.from_json!(File.read('invoice.json'))
+    #   GOBL.build(invoice, envelop: true) #=> A calculated, draft `GOBL::Envelope`
+    #
+    # @example Build a document and wrap in a non-draft envelope.
+    #   invoice = GOBL::Document.from_json!(File.read('invoice.json'))
+    #   GOBL.build(invoice, envelop: true, draft: false) #=> A calculated, non-draft `GOBL::Envelope`
+    #
+    # @example Build an envelope.
+    #   envelope = GOBL::Envelop.from_json!(File.read('envelope.json'))
+    #   GOBL.build(envelope) #=> A new, calculated GOBL::Envelope
+    #
+    # @example Build an envelope forcing it to be a non-draft.
+    #   envelope = GOBL::Envelop.from_json!(File.read('draft_envelope.json'))
+    #   GOBL.build(envelope, draft: false) #=> A new, non-draft GOBL::Envelope
+    def build(struct, envelop: nil, draft: nil)
+      check_struct_type struct, BUILDABLE_TYPES
+
+      response = request_action(:build, struct: struct,
+                                        envelop: envelop,
+                                        draft: draft)
+
+      raise ServiceError, response['error'] if response['error'].present?
+
+      GOBL::Struct.from_gobl! response['payload']
+    end
+
+    # Checks whether or not a document or envelope is valid according to the GOBL schema
+    #   and rules.
+    #
+    # @param struct [GOBL::Document, GOBL::Envelope] the document or the envelope to
+    #   validate.
+    #
+    # @return [GOBL::ValidationResult] the result of the validations.
+    #
+    # @example Validate an invalid document.
+    #   document =  GOBL::Document.from_json!(File.read('invalid_invoice.json'))
+    #   result = GOBL.validate(document)
+    #   result.valid? #=> false
+    #   result.errors #=> ['code: cannot be blank', 'totals: cannot be blank']
+    #
+    # @example Validate a valid envelope.
+    #   envelope = GOBL::Envelop.from_json!(File.read('valid_envelope.json'))
+    #   result = GOBL.validate(envelope)
+    #   result.valid? #=> true
+    #   result.errors #=> []
+    def validate(struct)
+      check_struct_type struct, VALIDATABLE_TYPES
+
+      response = request_action(:validate, struct: struct)
+
+      if response['error'].present?
+        ValidationResult.from_service_error(response['error'])
+      elsif response['payload']['ok']
+        ValidationResult.valid
+      else
+        raise 'Unexpected response from the service'
+      end
+    end
+
+    # Signs a document or envelope, calculating, enveloping and validating it first if
+    #   needed. The signing key will be the one configured in the server.
+    #
+    # @param struct [GOBL::Document, GOBL::Envelope] the envelop or document to sign.
+    #
+    # @return [GOBL::Envelope] a signed envelope.
+    #
+    # @raise [GOBL::Operations::ServiceError] if the service returns any errors.
+    #
+    # @example Sign an envelope.
+    #   envelope = GOBL::Envelop.from_json!(File.read('draft_envelope.json'))
+    #   GOBL.sign(envelope) #=> A new signed GOBL::Envelope
+    def sign(struct)
+      check_struct_type struct, SIGNABLE_TYPES
+
+      response = request_action(:sign, struct: struct)
+
+      raise ServiceError, response['error'] if response['error'].present?
+
+      GOBL::Struct.from_gobl! response['payload']
+    end
+
+    private
+
+    # Sends a request action to the GOBL service using the bulk endpoint. This endpoint
+    # allows to send multiple actions in one request but we only use it with one action.
+    def request_action(action, struct:, **params)
+      request = build_bulk_request(action, struct, params)
+
+      response = Net::HTTP.post(bulk_endpoint, request)
+      response.error! unless response.is_a?(Net::HTTPSuccess)
+
+      parts = parse_bulk_response(response)
+      parts.first # We're only requesting one action, the response is the first part
+    end
+
+    def build_bulk_request(action, struct, params)
+      payload = params.merge(data: Base64.encode64(struct.to_json.to_s))
+
+      { action: action, payload: payload }.to_json
+    end
+
+    def bulk_endpoint
+      @bulk_endpoint ||= URI::HTTP.build(
+        host: GOBL.config.service_host,
+        port: GOBL.config.service_port,
+        path: '/bulk'
+      )
+    end
+
+    def parse_bulk_response(response)
+      response.body.split("\n").map { |row| JSON.parse(row) }
+    end
+
+    def check_struct_type(struct, allowed_types)
+      return if allowed_types.any? { |klass| struct.is_a?(klass) }
+
+      message = "This operation only supports #{allowed_types.join(', ')} structs"
+      raise ArgumentError, message
+    end
+  end
+end