enel-ruby-sdk 0.1.2

data/lib/enel_x/endpoints/history.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require 'date'
+
+require_relative '../endpoint'
+require_relative '../errors'
+require_relative '../record'
+require_relative '../validators'
+
+module EnelX
+  module Endpoints
+    # History queries (PDF 5.6 to 5.10). Fields use the names of the PDF; the API has no
+    # webhooks, so this is the only way to learn what happened to a sale.
+    class History
+      # forms: name => [required fields, optional fields]
+      Query = Struct.new(:service, :path, :forms, :record, keyword_init: true)
+
+      BY_CUSTOMER = %w[empresa numeroCliente empresaParc].freeze
+      BY_DATE = %w[empresa dataOcorrencia empresaParc].freeze
+
+      QUERIES = {
+        subscription_history: Query.new(
+          service: :subscription_history, path: '/services/bdp/v1/subscription-history',
+          forms: { customer: [BY_CUSTOMER + %w[codProduto], []],
+                   date: [%w[empresa empresaParc dataOcorrencia], %w[operacao]] },
+          record: Subscription
+        ),
+        request_history: Query.new(
+          service: :request_history, path: '/services/bdp/v1/request-history',
+          forms: { customer: [BY_CUSTOMER, %w[codProduto]],
+                   date: [BY_DATE, %w[codProduto]] },
+          record: RequestHistoryItem
+        ),
+        invoice_history: Query.new(
+          service: :invoice_history, path: '/services/bdp/v1/invoice-history',
+          forms: { customer: [BY_CUSTOMER, %w[codProduto]],
+                   date: [BY_DATE, %w[codProduto]] },
+          record: InvoiceHistoryItem
+        ),
+        collections: Query.new(
+          service: :collections, path: '/services/bdp/v1/invoice',
+          forms: { date: [BY_DATE, %w[codProduto]] }, record: Collection
+        ),
+        movements: Query.new(
+          service: :movements, path: '/services/bdp/v1/movement',
+          forms: { customer: [BY_CUSTOMER + %w[codProduto], []] }, record: Movement
+        ),
+      }.freeze
+
+      OPERATIONS = %w[I C].freeze
+
+      def initialize(client, name)
+        @client = client
+        @query = QUERIES.fetch(name)
+      end
+
+      # Returns an Array of records. Needs `empresaParc` or a configured `partner_code`.
+      # [ASSUMPTION p.26-33] the PDF fixes no ClientSystem/ServerSystem/Functionality for
+      # the bdp queries, only "Read" for GET (p.11): Read/Read, the configured client
+      # system and XCustomerB2CBR, as in the writes.
+      def call(fields, context: nil)
+        params = build_params(normalize(fields))
+        endpoint = Endpoint.new(
+          service: @query.service, verb: :get, path: @query.path, operation: 'Read',
+          functionality: 'Read', server_system: 'XCustomerB2CBR'
+        )
+        items(@client.request(endpoint, payload: params, context:).body)
+      end
+
+      private
+
+      def normalize(fields)
+        unless fields.respond_to?(:to_h)
+          Validators.invalid('fields', 'must be a Hash with the PDF field names')
+        end
+        fields = fields.to_h.transform_keys(&:to_s)
+        partner = @client.configuration.partner_code
+        fields['empresaParc'] ||= partner.to_s unless partner.nil?
+        fields
+      end
+
+      def build_params(fields)
+        required, optional = @query.forms.fetch(form_for(fields))
+        unknown = fields.keys - required - optional
+        unless unknown.empty?
+          Validators.invalid(unknown.first,
+            'not a field of this query')
+        end
+
+        (required + optional).each_with_object({}) do |name, params|
+          next if optional.include?(name) && !fields.key?(name)
+
+          params[name] = value_for(name, fields[name])
+        end
+      end
+
+      def form_for(fields)
+        forms = @query.forms
+        return forms.keys.first if forms.one?
+
+        fields.key?('numeroCliente') ? :customer : :date
+      end
+
+      def value_for(name, value)
+        case name
+        when 'empresa' then Validators.company(name, value)
+        when 'numeroCliente' then Validators.text(name, value, max: 80)
+        when 'dataOcorrencia' then us_date(name, value)
+        when 'operacao' then Validators.one_of(name, value, OPERATIONS)
+        else Validators.text(name, value, max: 255)
+        end
+      end
+
+      # The API wants MM/DD/YYYY. Accepts Date, Time or a YYYY-MM-DD string.
+      def us_date(name, value)
+        date = if value.respond_to?(:to_date)
+                 value.to_date
+               else
+                 Date.strptime(value.to_s,
+                   '%Y-%m-%d')
+               end
+        date.strftime('%m/%d/%Y')
+      rescue Date::Error, NoMethodError
+        Validators.invalid(name, 'Date, Time or YYYY-MM-DD', value)
+      end
+
+      def items(body)
+        list = body.is_a?(Array) ? body : body.values.find { |value| value.is_a?(Array) }
+        unless list&.all?(Hash)
+          raise Error.new('unexpected history response', kind: :retryable)
+        end
+
+        list.map { |item| @query.record.from_hash(item) }
+      end
+    end
+  end
+end

data/lib/enel_x/endpoints/order_change.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative 'order_helpers'
+
+module EnelX
+  module Endpoints
+    # Alteração de Valores (PDF 5.4).
+    class OrderChange
+      include OrderHelpers
+
+      ENDPOINT = Endpoint.new(
+        service: :order_change, path: '/services/v1/third-party-billing/order/change',
+        **WRITE
+      )
+      ALLOWED = %w[
+        Nome Sobrenome Endereco EnderecoNumero Bairro Cidade CEP empresa numeroCliente
+        numParcelas valorParcela codProduto codOcorr dataOcorrencia codCanalVenda
+        numeroClienteEmpPar
+      ].freeze
+      # Table 7.1: 61 is "Alteração de débito de produto".
+      DEFAULT_OCCURRENCE = Reference::PartnerCode::CHANGE_CODE
+
+      def initialize(client)
+        @client = client
+      end
+
+      def call(fields, context: nil)
+        fields = stringify(fields, ALLOWED)
+        send_order(ENDPOINT, 'OrderChange', build(fields), context)
+      end
+
+      private
+
+      def build(fields)
+        person(fields).merge(
+          customer(fields), charge(fields), product(fields), occurrence(fields),
+          occurrence_date(fields), address(fields), partner_optionals(fields)
+        )
+      end
+
+      def charge(fields)
+        {
+          'numParcelas' => Validators.installments('numParcelas', fields['numParcelas']),
+          'valorParcela' => Validators.amount('valorParcela', fields['valorParcela']),
+        }
+      end
+
+      # [ASSUMPTION p.22] the 5.4.4 example sends codOcorr "32"; table 7.1 defines 61 for
+      # changes, so 61 is the default and any other code is left to the caller.
+      def occurrence(fields)
+        value = fields.fetch('codOcorr', DEFAULT_OCCURRENCE)
+        { 'codOcorr' => Validators.text('codOcorr', value, max: 255) }
+      end
+    end
+  end
+end

data/lib/enel_x/endpoints/order_disconnect.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative 'order_helpers'
+
+module EnelX
+  module Endpoints
+    # Cancelamento (PDF 5.5). Every required field must carry a value, otherwise the API
+    # processes nothing and returns nothing.
+    class OrderDisconnect
+      include OrderHelpers
+
+      ENDPOINT = Endpoint.new(
+        service: :order_disconnect,
+        path: '/services/v1/third-party-billing/order/disconnect', **WRITE
+      )
+      ALLOWED = %w[
+        Nome Sobrenome empresa numeroCliente valorParcela codProduto codOcorr
+        dataOcorrencia codCanalVenda Endereco EnderecoNumero Bairro Cidade CEP
+        numeroClienteEmpPar
+      ].freeze
+
+      def initialize(client)
+        @client = client
+      end
+
+      def call(fields, context: nil)
+        fields = stringify(fields, ALLOWED)
+        send_order(ENDPOINT, 'OrderDisconnect', build(fields), context)
+      end
+
+      private
+
+      # [ASSUMPTION p.25] the 5.5.4 example sends numParcelas but 5.5.2 does not list it:
+      # the SDK does not send it. The same example uses codOcorr "20", which is an
+      # automatic reason of 7.2; table 7.1 only allows 22 to 32 from the partner.
+      def build(fields)
+        person(fields).merge(
+          customer(fields), 'valorParcela' => amount(fields), **product(fields),
+          'codOcorr' => reason(fields), **occurrence_date(fields),
+          **address(fields), **partner_optionals(fields)
+        )
+      end
+
+      def amount(fields)
+        Validators.amount('valorParcela', fields['valorParcela'], allow_zero: true)
+      end
+
+      def reason(fields)
+        codes = Reference::PartnerCode.cancellation_reasons.map(&:code)
+        Validators.one_of('codOcorr', fields['codOcorr'], codes)
+      end
+    end
+  end
+end

data/lib/enel_x/endpoints/order_helpers.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative '../endpoint'
+require_relative '../reference/partner_code'
+require_relative '../validators'
+
+module EnelX
+  module Endpoints
+    # Field groups shared by sale, change and disconnect (PDF 5.3.2, 5.4.2, 5.5.2).
+    # Callers pass fields named as in the PDF; string or symbol keys both work.
+    module OrderHelpers
+      WRITE = { verb: :post, operation: 'Create', functionality: 'Create',
+                server_system: 'XCustomerB2CBR' }.freeze
+
+      private
+
+      def stringify(fields, allowed)
+        unless fields.respond_to?(:to_h)
+          Validators.invalid('fields', 'must be a Hash with the PDF field names')
+        end
+        fields = fields.to_h.transform_keys(&:to_s)
+        unknown = fields.keys - allowed
+        unless unknown.empty?
+          Validators.invalid(unknown.first,
+            'not a field of this operation')
+        end
+        fields
+      end
+
+      def person(fields)
+        {
+          'Nome' => Validators.text('Nome', fields['Nome'], max: 40),
+          'Sobrenome' => Validators.text('Sobrenome', fields['Sobrenome'], max: 40),
+        }
+      end
+
+      def address(fields)
+        {
+          'Endereco' => Validators.text('Endereco', fields['Endereco'], max: 255),
+          'EnderecoNumero' =>
+            Validators.text('EnderecoNumero', fields['EnderecoNumero'], max: 100),
+          # [ASSUMPTION p.24] 5.5.2 lists Bairro as String(255); 40 applies everywhere
+          # because a longer value makes the sale return nothing (p.15).
+          'Bairro' => Validators.text('Bairro', fields['Bairro'], max: 40),
+          'Cidade' => Validators.text('Cidade', fields['Cidade'], max: 255),
+          'CEP' => Validators.cep('CEP', fields['CEP']),
+        }
+      end
+
+      def customer(fields)
+        {
+          'empresa' => Validators.company('empresa', fields['empresa']),
+          'numeroCliente' =>
+            Validators.text('numeroCliente', fields['numeroCliente'], max: 80),
+        }
+      end
+
+      def product(fields)
+        { 'codProduto' => Validators.text('codProduto', fields['codProduto'], max: 255) }
+      end
+
+      def occurrence_date(fields)
+        { 'dataOcorrencia' => Validators.date('dataOcorrencia',
+          fields['dataOcorrencia']) }
+      end
+
+      def partner_optionals(fields)
+        %w[codCanalVenda numeroClienteEmpPar].each_with_object({}) do |name, hash|
+          next unless fields.key?(name)
+
+          hash[name] = Validators.text(name, fields[name], max: 255, required: false)
+        end
+      end
+
+      def send_order(endpoint, root, body, context)
+        @client.request(endpoint, payload: { root => body }, context:)
+      end
+    end
+  end
+end

data/lib/enel_x/endpoints/order_sale.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'date'
+
+require_relative '../attachment'
+require_relative 'order_helpers'
+
+module EnelX
+  module Endpoints
+    # Solicitação de Venda (PDF 5.3), residential and business customers.
+    class OrderSale
+      include OrderHelpers
+
+      ENDPOINT = Endpoint.new(
+        service: :order_sale, path: '/services/v2/third-party-billing/order/sale',
+        **WRITE
+      )
+      ALLOWED = %w[
+        Nome Sobrenome dtNascimento Telefone Email Endereco EnderecoNumero Bairro Cidade
+        CEP empresa numeroCliente CPF numParcelas valorParcela codProduto dataOcorrencia
+        codCanalVenda numeroClienteEmpPar anexos CNPJ NomeEmpresa
+      ].freeze
+
+      def initialize(client)
+        @client = client
+      end
+
+      # Success only means "received": the sale is confirmed by occurrences 996 and 998
+      # (Consulta de Ocorrências). Cidade must be the exact IBGE name; the SDK cannot
+      # check that.
+      def call(fields, context: nil)
+        body = build(stringify(fields, ALLOWED))
+        warn_past_date(body['dataOcorrencia'])
+        send_order(ENDPOINT, 'OrderSale', body, context)
+      end
+
+      private
+
+      def build(fields)
+        business(fields).merge(person(fields), contact(fields), address(fields),
+          customer(fields), charge(fields), product(fields),
+          occurrence_date(fields), partner_optionals(fields),
+          'anexos' => attachments(fields['anexos']))
+      end
+
+      def business(fields)
+        return {} unless fields.key?('CNPJ')
+
+        {
+          'CNPJ' => Validators.digits('CNPJ', fields['CNPJ'], exactly: 14),
+          'NomeEmpresa' => Validators.text('NomeEmpresa', fields['NomeEmpresa'], max: 40),
+        }
+      end
+
+      def contact(fields)
+        contact = {
+          'Telefone' => Validators.phone('Telefone', fields['Telefone']),
+          'Email' => Validators.email('Email', fields['Email']),
+          'CPF' => Validators.digits('CPF', fields['CPF']),
+        }
+        return contact unless present?(fields['dtNascimento'])
+
+        contact.merge('dtNascimento' => Validators.date('dtNascimento',
+          fields['dtNascimento']))
+      end
+
+      def charge(fields)
+        {
+          'numParcelas' => Validators.installments('numParcelas', fields['numParcelas']),
+          'valorParcela' => Validators.amount('valorParcela', fields['valorParcela']),
+        }
+      end
+
+      def attachments(list)
+        items = Array(list).map { |item| Attachment.coerce(item) }
+        if items.empty?
+          Validators.invalid('anexos',
+            'at least one attachment is required')
+        end
+        unless items.any?(&:adhesion?)
+          Validators.invalid('anexos', 'one attachment must be of type Termo de Adesão')
+        end
+        items.map(&:to_h)
+      end
+
+      def present?(value)
+        !value.nil? && !value.to_s.strip.empty?
+      end
+
+      def warn_past_date(date)
+        return unless Date.strptime(date, '%Y-%m-%d') < Date.today
+
+        @client.configuration.logger.warn(
+          "EnelX order_sale: dataOcorrencia #{date} is in the past; billing periods " \
+          'before the start date may not be invoiced (PDF 5.3.2)',
+        )
+      end
+    end
+  end
+end

data/lib/enel_x/error_catalog.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+
+module EnelX
+  # PDF 7.3 as data. Specific data errors come first because many of them also start
+  # with "ERROR." or "INTERNAL ERROR", which are retryable only when generic.
+  module ErrorCatalog
+    Entry = Struct.new(:pattern, :kind, :reason, :error_class)
+
+    def self.data(pattern, reason = nil, error_class = Error)
+      Entry.new(pattern, :data, reason, error_class)
+    end
+
+    def self.retryable(pattern)
+      Entry.new(pattern, :retryable, nil, Error)
+    end
+
+    def self.prefixes(lead, *tails)
+      /\A#{Regexp.escape(lead)}(?:#{tails.map { |tail| Regexp.escape(tail) }.join('|')})/
+    end
+
+    ENTRIES = [
+      data(/\AERROR[.:] Account not found/, :account_not_found, UcNotFound),
+      data(/\AERROR: POS not found/, :pos_not_found, UcNotFound),
+      # [ASSUMPTION p.37] the PDF does not say Contract/Asset not found mean a missing UC,
+      # so they are not UcNotFound.
+      data(/\AERROR\. Contract not found/, :contract_not_found),
+      data(/\AERROR\. Asset not found/, :asset_not_found),
+      data(/\AINTERNAL ERROR\. This opportunity already exists/, :opportunity_exists),
+      data(/\AINTERNAL ERROR: An Account with the provided document already exists/,
+        :document_in_use),
+      data(/\AINTERNAL ERROR: An Account with the provided email already exists/,
+        :email_in_use),
+      data(/\AINTERNAL ERROR: An Account with the provided email and document/,
+        :email_and_document_in_use),
+      data(/\AError on CartAPI with transactionID/),
+      data(prefixes('ERROR. ', 'Address ', 'Address.PointOfService.', 'BillingProfile.',
+        'CatalogItem', 'Contact', 'Format of Identity', 'Identity',
+        'Missing mandatory field', 'PointOfService', 'The Identity',
+        'There is not a valid contact')),
+      data(prefixes('ERROR: ', 'Address section', 'Market Account validation',
+        'Missing identityNumber', 'You must fill both')),
+      data(prefixes('INTERNAL ERROR: ', 'Address with id', 'In Address',
+        'In BillingProfile',
+        'In Contact', 'In Identity', 'In Update Billing', 'Missing Address',
+        'No Billing Profile')),
+      # [ASSUMPTION p.22, p.37] only a bare "Bad Request" is the generic retryable error;
+      # "Bad Request. <detail>" (example 2 of 5.4.4) names a data problem.
+      retryable(/\ABad Request\.?\z/),
+      retryable(/\AERROR\./),
+      retryable(/\AGateway Timeout/),
+      retryable(/\AINTERNAL ERROR/),
+      retryable(/\AResponse code 500 mapped as failure/),
+      retryable(/\AServer Error/),
+    ].freeze
+
+    # Unknown messages are :data, so the consumer never loops on a data error.
+    UNKNOWN = Entry.new(nil, :data, nil, Error)
+
+    module_function
+
+    def classify(message)
+      text = message.to_s.gsub(/\s+/, ' ').strip
+      ENTRIES.find { |entry| entry.pattern.match?(text) } || UNKNOWN
+    end
+
+    def build_error(message, code: nil, transaction_id: nil)
+      entry = classify(message)
+      entry.error_class.new(
+        message, kind: entry.kind, reason: entry.reason, code:,
+        transaction_id:
+      )
+    end
+  end
+end

data/lib/enel_x/errors.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module EnelX
+  # kind: :retryable (resend as is), :data (fix the input) or :configuration.
+  class Error < StandardError
+    attr_reader :kind, :code, :transaction_id, :reason
+
+    def initialize(message = nil, kind: :data, code: nil, transaction_id: nil,
+      reason: nil)
+      super(message)
+      @kind = kind
+      @code = code
+      @transaction_id = transaction_id
+      @reason = reason
+    end
+  end
+
+  # Bad credentials, host or persistent 401: the consumer must fix its setup.
+  class ConfigurationError < Error
+    def initialize(message = nil, **)
+      super(message, **, kind: :configuration)
+    end
+  end
+
+  # Raised before any network call. value_preview is already filtered of personal data.
+  class ValidationError < Error
+    attr_reader :field, :limit, :value_preview
+
+    def initialize(message, field:, limit: nil, value_preview: nil)
+      super(message, kind: :data)
+      @field = field
+      @limit = limit
+      @value_preview = value_preview
+    end
+  end
+
+  # The distributor does not know the consumption unit (PDF 7.3: Account/POS not found).
+  class UcNotFound < Error; end
+end

data/lib/enel_x/filter.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module EnelX
+  # Removes secrets, attachments and personal data before anything leaves the SDK.
+  module Filter
+    FILTERED = '[FILTERED]'
+
+    HIDDEN_KEYS = %w[
+      authorization clientsecret accesstoken conteudobase64 nome sobrenome bairro cidade
+      cep telefone email dtnascimento nomeempresa commoditycustomername
+      contractbillingaddress addressdata
+    ].freeze
+    HIDDEN_PREFIXES = %w[endereco].freeze
+    MASKED_KEYS = %w[cpf cnpj identitynumber commodityidentitynumber].freeze
+
+    module_function
+
+    def apply(value, key = nil)
+      case value
+      when Hash then value.to_h { |name, item| [name, apply(item, name)] }
+      when Array then value.map { |item| apply(item, key) }
+      else scalar(value, normalize(key))
+      end
+    end
+
+    def scalar(value, key)
+      return value if value.nil? || key.nil?
+      return FILTERED if hidden?(key)
+
+      MASKED_KEYS.include?(key) ? mask(value) : value
+    end
+
+    def hidden?(key)
+      HIDDEN_KEYS.include?(key) || HIDDEN_PREFIXES.any? do |prefix|
+        key.start_with?(prefix)
+      end
+    end
+
+    # Keeps only the last two digits (PDF documents are CPF or CNPJ).
+    def mask(value)
+      digits = value.to_s.gsub(/\D/, '')
+      case digits.length
+      when 11 then "***.***.***-#{digits[-2..]}"
+      when 14 then "**.***.***/****-#{digits[-2..]}"
+      else FILTERED
+      end
+    end
+
+    def normalize(key)
+      key.to_s.downcase.gsub(/[^a-z0-9]/, '') unless key.nil?
+    end
+  end
+end

data/lib/enel_x/headers.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module EnelX
+  # Per-call headers from PDF 5.1. Authorization is added by the client.
+  module Headers
+    module_function
+
+    def build(operation:, functionality:, client_system:, server_system:)
+      {
+        'Content-Type' => 'application/json; charset=UTF-8',
+        'cache-control' => 'no-cache',
+        'TransactionID' => SecureRandom.uuid,
+        'DateTimeMessage' => timestamp(Time.now),
+        'Operation' => operation,
+        'Functionality' => functionality,
+        'ClientSystem' => client_system,
+        'ServerSystem' => server_system,
+      }
+    end
+
+    # YYYYMMDDHH24MISSmil: 17 characters, milliseconds last.
+    def timestamp(time)
+      time.strftime('%Y%m%d%H%M%S%L')
+    end
+  end
+end

data/lib/enel_x/http.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'openssl'
+require 'timeout'
+require 'uri'
+
+require_relative 'errors'
+
+module EnelX
+  # Thin net/http wrapper: network failures become retryable EnelX::Error.
+  class Http
+    Response = Struct.new(:status, :body)
+
+    NETWORK_ERRORS = [
+      Timeout::Error, SocketError, SystemCallError, IOError, EOFError, OpenSSL::SSL::SSLError,
+      Net::OpenTimeout, Net::ReadTimeout
+    ].freeze
+
+    def initialize(open_timeout:, read_timeout:)
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+    end
+
+    def request(method, url, headers: {}, body: nil)
+      uri = URI(url)
+      request = Net::HTTP.const_get(method.to_s.capitalize).new(uri)
+      headers.each { |name, value| request[name] = value }
+      request.body = body if body
+
+      response = connection(uri).request(request)
+      Response.new(response.code.to_i, response.body.to_s)
+    rescue *NETWORK_ERRORS => e
+      raise Error.new("network failure: #{e.class}", kind: :retryable)
+    end
+
+    private
+
+    def connection(uri)
+      Net::HTTP.new(uri.host, uri.port).tap do |http|
+        http.use_ssl = uri.scheme == 'https'
+        http.open_timeout = @open_timeout
+        http.read_timeout = @read_timeout
+      end
+    end
+  end
+end