nfe-io 0.3.2 → 1.0.0

data/lib/nfe/resources/dto/addresses/address_lookup_response.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Nfe
+  # Immutable value object for a single address as returned by the NFE.io
+  # +address.api.nfe.io/v2+ lookup API. All fields are optional; {from_api}
+  # maps API camelCase keys onto snake_case members and is nil-tolerant
+  # (+from_api(nil)+ returns +nil+).
+  #
+  # +city+ is hydrated into a nested {Nfe::Address::City} value object
+  # (+{code, name}+). +postal_code+, +number+, +number_min+ and +number_max+
+  # are kept as +String+, never coerced to Integer (preserves leading zeros).
+  class Address < Data.define(
+    :street,
+    :street_suffix,
+    :number,
+    :number_min,
+    :number_max,
+    :additional_information,
+    :district,
+    :postal_code,
+    :city,
+    :state,
+    :country
+  )
+    # Nested value object for the IBGE city code/name pair returned inside an
+    # address item. Both members are optional and nil-tolerant.
+    class City < Data.define(:code, :name)
+      # @param payload [Hash, nil] the +city+ sub-object.
+      # @return [Nfe::Address::City, nil] +nil+ when +payload+ is +nil+.
+      def self.from_api(payload)
+        return nil if payload.nil?
+
+        new(
+          code: payload["code"]&.to_s,
+          name: payload["name"]
+        )
+      end
+    end
+
+    # @param payload [Hash, nil] a single address object.
+    # @return [Nfe::Address, nil] +nil+ when +payload+ is +nil+.
+    def self.from_api(payload)
+      return nil if payload.nil?
+
+      new(
+        street: payload["street"],
+        street_suffix: payload["streetSuffix"],
+        number: payload["number"]&.to_s,
+        number_min: payload["numberMin"]&.to_s,
+        number_max: payload["numberMax"]&.to_s,
+        additional_information: payload["additionalInformation"],
+        district: payload["district"],
+        postal_code: payload["postalCode"]&.to_s,
+        city: Nfe::Address::City.from_api(payload["city"]),
+        state: payload["state"],
+        country: payload["country"]
+      )
+    end
+  end
+
+  # Immutable value object wrapping the addresses returned by a lookup.
+  # {from_api} is nil-tolerant and accepts BOTH response shapes the API uses:
+  # the list shape (+{ "addresses" => [...] }+, e.g. term/$filter search) and
+  # the single-result shape the postal-code lookup actually returns
+  # (+{ "address" => {...} }+) — the latter is normalized into a one-element
+  # +addresses+ list, so callers always read +response.addresses+.
+  class AddressLookupResponse < Data.define(:addresses)
+    # @param payload [Hash, nil] the parsed lookup response body.
+    # @return [Nfe::AddressLookupResponse, nil] +nil+ when +payload+ is +nil+.
+    def self.from_api(payload)
+      return nil if payload.nil?
+
+      raw = payload["addresses"] || [payload["address"]].compact
+      new(addresses: raw.map { |item| Nfe::Address.from_api(item) })
+    end
+  end
+end

data/lib/nfe/resources/dto/company.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Nfe
+  # Immutable value object for a company (emitente) as returned by the NFE.io
+  # +api.nfe.io/v1+ entity API.
+  #
+  # Hand-written (rather than reusing the mangled generated +contribuintes_v2+
+  # DTOs) so the public shape stays clean and snake_case. {from_api} maps the
+  # API camelCase keys onto the snake_case members, drops unknown keys, and is
+  # nil-tolerant (+from_api(nil)+ returns +nil+).
+  #
+  # +federal_tax_number+ is kept as a +String+ — never coerced to +Integer+ —
+  # so future alphanumeric CNPJ (IN RFB 2.229/2024) is preserved.
+  class Company < Data.define(
+    :id,
+    :name,
+    :trade_name,
+    :federal_tax_number,
+    :email,
+    :status,
+    :tax_regime,
+    :municipal_tax_number,
+    :address,
+    :state_taxes,
+    :municipal_taxes,
+    :environment,
+    :account_id,
+    :created_on,
+    :modified_on
+  )
+    # Build a {Nfe::Company} from an API payload.
+    #
+    # @param payload [Hash, nil] the unwrapped company object.
+    # @return [Nfe::Company, nil] +nil+ when +payload+ is +nil+.
+    def self.from_api(payload)
+      return nil if payload.nil?
+
+      new(
+        id: payload["id"],
+        name: payload["name"],
+        trade_name: payload["tradeName"],
+        federal_tax_number: stringify(payload["federalTaxNumber"]),
+        email: payload["email"],
+        status: payload["status"],
+        tax_regime: payload["taxRegime"],
+        municipal_tax_number: payload["municipalTaxNumber"],
+        address: payload["address"],
+        state_taxes: payload["stateTaxes"],
+        municipal_taxes: payload["municipalTaxes"],
+        environment: payload["environment"],
+        account_id: payload["accountId"],
+        created_on: payload["createdOn"],
+        modified_on: payload["modifiedOn"]
+      )
+    end
+
+    # Coerce a tax number to a +String+ without numeric coercion, preserving
+    # alphanumeric CNPJ. +nil+ stays +nil+.
+    #
+    # @api private
+    def self.stringify(value)
+      value&.to_s
+    end
+  end
+end

data/lib/nfe/resources/dto/consumer_invoice.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Nfe
+  # Immutable value object for a consumer invoice (NFC-e — Nota Fiscal de
+  # Consumidor Eletrônica) emitted through the NFE.io +api.nfse.io+ v2 API.
+  #
+  # Hand-written (rather than reusing the verbose generated +nf-consumidor-v2+
+  # DTOs) so the public shape stays clean and snake_case. {from_api} maps the
+  # API camelCase keys onto the snake_case members, drops unknown keys, and is
+  # nil-tolerant (+from_api(nil)+ returns +nil+). The full parsed payload is
+  # preserved under +raw+ for forward compatibility.
+  #
+  # Shape mirrors +POST /v2/companies/{id}/consumerinvoices+ and
+  # +GET .../consumerinvoices/{id}+ per +nf-consumidor-v2.yaml+.
+  #
+  # +number+/+serie+ are kept as returned (no Integer coercion) so leading
+  # zeros and string representations from the API survive untouched.
+  class ConsumerInvoice < Data.define(
+    :id,
+    :status,
+    :flow_status,
+    :flow_message,
+    :environment,
+    :access_key,
+    :number,
+    :serie,
+    :total_amount,
+    :issued_on,
+    :created_on,
+    :modified_on,
+    :cancelled_on,
+    :raw
+  )
+    # Build a {Nfe::ConsumerInvoice} from an API payload.
+    #
+    # @param payload [Hash, nil] the parsed consumer-invoice object.
+    # @return [Nfe::ConsumerInvoice, nil] +nil+ when +payload+ is +nil+.
+    def self.from_api(payload)
+      return nil if payload.nil?
+
+      new(
+        id: payload["id"],
+        status: payload["status"],
+        flow_status: payload["flowStatus"],
+        flow_message: payload["flowMessage"],
+        environment: payload["environment"],
+        access_key: payload["accessKey"],
+        number: payload["number"],
+        serie: payload["serie"],
+        total_amount: payload["totalAmount"],
+        issued_on: payload["issuedOn"],
+        created_on: payload["createdOn"],
+        modified_on: payload["modifiedOn"],
+        cancelled_on: payload["cancelledOn"],
+        raw: payload
+      )
+    end
+  end
+end

data/lib/nfe/resources/dto/consumer_invoice_query/tax_coupon.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module Nfe
+  # Immutable value object for a consumer-invoice tax coupon (CFe-SAT)
+  # returned by the +nfe.api.nfe.io+ query API
+  # (+GET /v1/consumerinvoices/coupon/{accessKey}+).
+  #
+  # This is the QUERY (consulta) of an already-issued coupon by access key and
+  # is DISTINCT from {Nfe::ConsumerInvoice} (the emission model handled by
+  # {Nfe::Resources::ConsumerInvoices}) — different host and API version.
+  #
+  # All fields are optional; {from_api} maps the API camelCase keys onto the
+  # snake_case members, hydrates the nested value objects, and is nil-tolerant
+  # (+from_api(nil)+ returns +nil+). The nested objects ({Issuer}, {Buyer},
+  # {Total}, {Delivery}, {AdditionalInformation}, {Item}, {Payment}) keep only a
+  # pragmatic subset of the most common fields, mapped against the real CFe-SAT
+  # +TaxCouponResource+ shape.
+  class TaxCoupon < Data.define(
+    :current_status,
+    :number,
+    :sat_serie,
+    :software_version,
+    :software_federal_tax_number,
+    :access_key,
+    :cashier,
+    :issued_on,
+    :created_on,
+    :xml_version,
+    :issuer,
+    :buyer,
+    :totals,
+    :delivery,
+    :additional_information,
+    :items,
+    :payment
+  )
+    # Issuer (emitente / +emit+) of the coupon.
+    class Issuer < Data.define(:federal_tax_number, :name, :trade_name, :state_tax_number)
+      def self.from_api(payload)
+        return nil if payload.nil?
+
+        new(
+          federal_tax_number: payload["federalTaxNumber"]&.to_s,
+          name: payload["name"],
+          trade_name: payload["tradeName"],
+          state_tax_number: payload["stateTaxNumber"]&.to_s
+        )
+      end
+    end
+
+    # Buyer (destinatário / consumidor / +dest+) of the coupon.
+    class Buyer < Data.define(:federal_tax_number, :name)
+      def self.from_api(payload)
+        return nil if payload.nil?
+
+        new(
+          federal_tax_number: payload["federalTaxNumber"]&.to_s,
+          name: payload["name"]
+        )
+      end
+    end
+
+    # Monetary totals of the coupon (+total+). +total_amount+ is the approximate
+    # tax amount (vCFeLei12741) and +coupon_amount+ is the coupon grand total
+    # (vCFe).
+    class Total < Data.define(:total_amount, :coupon_amount)
+      def self.from_api(payload)
+        return nil if payload.nil?
+
+        new(
+          total_amount: payload["totalAmount"],
+          coupon_amount: payload["couponAmount"]
+        )
+      end
+    end
+
+    # Delivery location (+entrega+) — the coupon delivery group only carries an
+    # address.
+    class Delivery < Data.define(:address)
+      def self.from_api(payload)
+        return nil if payload.nil?
+
+        new(
+          address: Address.from_api(payload["address"])
+        )
+      end
+    end
+
+    # Pragmatic subset of a CFe-SAT address (+enderEmit+ / +entrega.address+).
+    class Address < Data.define(:street, :number, :district, :postal_code, :city, :state, :country)
+      def self.from_api(payload)
+        return nil if payload.nil?
+
+        new(
+          street: payload["street"],
+          number: payload["number"]&.to_s,
+          district: payload["district"],
+          postal_code: payload["postalCode"]&.to_s,
+          city: payload["city"],
+          state: payload["state"],
+          country: payload["country"]
+        )
+      end
+    end
+
+    # Free-form additional information block (+infAdic+).
+    class AdditionalInformation < Data.define(:taxpayer)
+      def self.from_api(payload)
+        return nil if payload.nil?
+
+        new(
+          taxpayer: payload["taxpayer"]
+        )
+      end
+    end
+
+    # A single coupon line item (+det+ / +prod+).
+    class Item < Data.define(:code, :description, :quantity, :unit_amount, :net_amount, :gross_amount, :cfop)
+      def self.from_api(payload)
+        return nil if payload.nil?
+
+        new(
+          code: payload["code"]&.to_s,
+          description: payload["description"],
+          quantity: payload["quantity"],
+          unit_amount: payload["unitAmount"],
+          net_amount: payload["netAmount"],
+          gross_amount: payload["grossAmount"],
+          cfop: payload["cfop"]
+        )
+      end
+    end
+
+    # A single payment-method detail (+pgto.MP+).
+    class PaymentDetail < Data.define(:method, :amount, :card)
+      def self.from_api(payload)
+        return nil if payload.nil?
+
+        new(
+          method: payload["method"],
+          amount: payload["amount"],
+          card: payload["card"]
+        )
+      end
+    end
+
+    # Payment group for the coupon (+pgto+). +pay_back+ is the change/troco
+    # (vTroco); +payment_details+ holds one entry per payment method.
+    class Payment < Data.define(:pay_back, :payment_details)
+      def self.from_api(payload)
+        return nil if payload.nil?
+
+        new(
+          pay_back: payload["payBack"],
+          payment_details: (payload["paymentDetails"] || []).map { |d| PaymentDetail.from_api(d) }
+        )
+      end
+    end
+
+    # Build a {Nfe::TaxCoupon} from an API payload.
+    #
+    # @param payload [Hash, nil] the parsed coupon object.
+    # @return [Nfe::TaxCoupon, nil] +nil+ when +payload+ is +nil+.
+    # rubocop:disable Metrics/AbcSize -- wide value-object mapping kept inline for Steep keyword-arg verification
+    def self.from_api(payload)
+      return nil if payload.nil?
+
+      new(
+        current_status: payload["currentStatus"],
+        number: payload["number"],
+        sat_serie: payload["satSerie"]&.to_s,
+        software_version: payload["softwareVersion"],
+        software_federal_tax_number: payload["softwareFederalTaxNumber"]&.to_s,
+        access_key: payload["accessKey"]&.to_s,
+        cashier: payload["cashier"],
+        issued_on: payload["issuedOn"],
+        created_on: payload["createdOn"],
+        xml_version: payload["xmlVersion"],
+        issuer: Issuer.from_api(payload["issuer"]),
+        buyer: Buyer.from_api(payload["buyer"]),
+        totals: Total.from_api(payload["totals"]),
+        delivery: Delivery.from_api(payload["delivery"]),
+        additional_information: AdditionalInformation.from_api(payload["additionalInformation"]),
+        items: (payload["items"] || []).map { |i| Item.from_api(i) },
+        payment: Payment.from_api(payload["payment"])
+      )
+    end
+    # rubocop:enable Metrics/AbcSize
+  end
+end

data/lib/nfe/resources/dto/inbound_invoice_metadata.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Nfe
+  # Immutable value object for the metadata of an inbound document (CT-e or
+  # supplier NF-e) returned by the +api.nfse.io+ inbound endpoints when looked
+  # up by 44-digit access key, or by an event lookup.
+  #
+  # Hand-written so the public surface stays small and snake_case. {from_api}
+  # maps the API camelCase keys onto snake_case members, drops unknown keys, and
+  # is nil-tolerant. The full payload is preserved in +details+ (including the
+  # webhook-v2 +productInvoices+ array, when present) so callers can read fields
+  # the SDK does not surface yet.
+  class InboundInvoiceMetadata < Data.define(
+    :access_key,
+    :nsu,
+    :status,
+    :name_sender,
+    :federal_tax_number_sender,
+    :total_invoice_amount,
+    :issued_on,
+    :product_invoices,
+    :details
+  )
+    # Build a {Nfe::InboundInvoiceMetadata} from an API payload.
+    #
+    # @param payload [Hash, nil] the inbound document metadata object.
+    # @return [Nfe::InboundInvoiceMetadata, nil] +nil+ when +payload+ is +nil+.
+    def self.from_api(payload)
+      return nil if payload.nil?
+
+      new(
+        access_key: payload["accessKey"] || payload["accesskey"],
+        nsu: payload["nsu"],
+        status: payload["status"],
+        name_sender: payload["nameSender"],
+        federal_tax_number_sender: stringify(payload["federalTaxNumberSender"]),
+        total_invoice_amount: payload["totalInvoiceAmount"],
+        issued_on: payload["issuedOn"],
+        product_invoices: payload["productInvoices"],
+        details: payload
+      )
+    end
+
+    # Coerce a tax number to a +String+ without numeric coercion. +nil+ stays
+    # +nil+.
+    #
+    # @api private
+    def self.stringify(value)
+      value&.to_s
+    end
+  end
+end

data/lib/nfe/resources/dto/inbound_settings.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Nfe
+  # Immutable value object for the inbound auto-fetch settings returned by the
+  # CT-e / inbound NF-e endpoints on +api.nfse.io+
+  # (+/v2/companies/{id}/inbound/(transportation|product)invoices+).
+  #
+  # Hand-written (the +consulta-cte-v2+ generated tree does not expose a clean
+  # settings shape) so the public surface stays small and snake_case.
+  # {from_api} maps the API camelCase keys onto the snake_case members, drops
+  # unknown keys, and is nil-tolerant (+from_api(nil)+ returns +nil+). The raw
+  # payload is preserved in +details+ so callers can read fields the SDK does
+  # not surface yet.
+  class InboundSettings < Data.define(
+    :id,
+    :status,
+    :start_from_nsu,
+    :start_from_date,
+    :environment_sefaz,
+    :automatic_manifesting,
+    :webhook_version,
+    :created_on,
+    :modified_on,
+    :details
+  )
+    # Build a {Nfe::InboundSettings} from an API payload.
+    #
+    # @param payload [Hash, nil] the inbound settings object.
+    # @return [Nfe::InboundSettings, nil] +nil+ when +payload+ is +nil+.
+    def self.from_api(payload)
+      return nil if payload.nil?
+
+      new(
+        id: payload["id"],
+        status: payload["status"],
+        start_from_nsu: payload["startFromNsu"],
+        start_from_date: payload["startFromDate"],
+        environment_sefaz: payload["environmentSefaz"] || payload["environmentSEFAZ"],
+        automatic_manifesting: payload["automaticManifesting"],
+        webhook_version: payload["webhookVersion"],
+        created_on: payload["createdOn"],
+        modified_on: payload["modifiedOn"],
+        details: payload
+      )
+    end
+  end
+end

data/lib/nfe/resources/dto/legal_entity_lookup/legal_entity_responses.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "nfe/resources/dto/legal_entity_lookup/state_tax_legal_entity"
+
+module Nfe
+  # Immutable value object for a legal entity (pessoa jurídica) as returned by
+  # the NFE.io +legalentity.api.nfe.io+ +basicInfo+ lookup. All fields are
+  # optional; {from_api} maps API camelCase keys onto snake_case members and is
+  # nil-tolerant (+from_api(nil)+ returns +nil+).
+  #
+  # +federal_tax_number+ is kept as a +String+ (CNPJ), never coerced to
+  # Integer, preserving future alphanumeric CNPJ. +address+, +phones+,
+  # +partners+ and +economic_activities+ are passed through opaquely.
+  class LegalEntity < Data.define(
+    :federal_tax_number,
+    :name,
+    :trade_name,
+    :status,
+    :status_on,
+    :status_reason,
+    :legal_nature,
+    :size,
+    :opened_on,
+    :issued_on,
+    :special_status,
+    :special_status_on,
+    :responsable_entity,
+    :share_capital,
+    :registration_unit,
+    :unit,
+    :address,
+    :phones,
+    :email,
+    :economic_activities,
+    :partners
+  )
+    # @param payload [Hash, nil] the unwrapped legal-entity object.
+    # @return [Nfe::LegalEntity, nil] +nil+ when +payload+ is +nil+.
+    def self.from_api(payload)
+      return nil if payload.nil?
+
+      new(
+        federal_tax_number: payload["federalTaxNumber"]&.to_s,
+        name: payload["name"],
+        trade_name: payload["tradeName"],
+        status: payload["status"],
+        status_on: payload["statusOn"],
+        status_reason: payload["statusReason"],
+        legal_nature: payload["legalNature"],
+        size: payload["size"],
+        opened_on: payload["openedOn"],
+        issued_on: payload["issuedOn"],
+        special_status: payload["specialStatus"],
+        special_status_on: payload["specialStatusOn"],
+        responsable_entity: payload["responsableEntity"],
+        share_capital: payload["shareCapital"],
+        registration_unit: payload["registrationUnit"],
+        unit: payload["unit"],
+        address: payload["address"],
+        phones: payload["phones"],
+        email: payload["email"],
+        economic_activities: payload["economicActivities"],
+        partners: payload["partners"]
+      )
+    end
+  end
+
+  # Immutable wrapper for a +basicInfo+ lookup response.
+  class LegalEntityBasicInfoResponse < Data.define(:legal_entity)
+    # @param payload [Hash, nil] the parsed response body.
+    # @return [Nfe::LegalEntityBasicInfoResponse, nil] +nil+ when +payload+ is +nil+.
+    def self.from_api(payload)
+      return nil if payload.nil?
+
+      new(
+        legal_entity: Nfe::LegalEntity.from_api(payload["legalEntity"] || payload)
+      )
+    end
+  end
+
+  # Immutable wrapper for a +stateTaxInfo+ lookup response. The body wraps a
+  # +legalEntity+ object with the state-tax shape ({Nfe::StateTaxLegalEntity});
+  # all state-tax data lives there (inside +stateTaxes+), not at the top level.
+  class LegalEntityStateTaxResponse < Data.define(:legal_entity)
+    # @param payload [Hash, nil] the parsed response body.
+    # @return [Nfe::LegalEntityStateTaxResponse, nil] +nil+ when +payload+ is +nil+.
+    def self.from_api(payload)
+      return nil if payload.nil?
+
+      new(
+        legal_entity: Nfe::StateTaxLegalEntity.from_api(payload["legalEntity"] || payload)
+      )
+    end
+  end
+
+  # Immutable wrapper for a +stateTaxForInvoice+ / +stateTaxSuggestedForInvoice+
+  # lookup response. Same +legalEntity+ state-tax shape as
+  # {Nfe::LegalEntityStateTaxResponse}; the per-IE status enum is extended for
+  # invoice evaluation but the structure is identical.
+  class LegalEntityStateTaxForInvoiceResponse < Data.define(:legal_entity)
+    # @param payload [Hash, nil] the parsed response body.
+    # @return [Nfe::LegalEntityStateTaxForInvoiceResponse, nil] +nil+ when +payload+ is +nil+.
+    def self.from_api(payload)
+      return nil if payload.nil?
+
+      new(
+        legal_entity: Nfe::StateTaxLegalEntity.from_api(payload["legalEntity"] || payload)
+      )
+    end
+  end
+end