nfe-io 0.3.2 → 1.0.0

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

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Nfe
+  # Immutable value object for the +legalEntity+ object returned by the NFE.io
+  # state-tax lookup endpoints (+stateTaxInfo+, +stateTaxForInvoice+,
+  # +stateTaxSuggestedForInvoice+) on +legalentity.api.nfe.io+.
+  #
+  # This is a DIFFERENT shape from the +basicInfo+ {Nfe::LegalEntity}: it carries
+  # the company-level tax-regime fields plus a +stateTaxes+ collection of state
+  # registrations (Inscrições Estaduais). All fields are optional; {from_api}
+  # maps API camelCase keys onto snake_case members and is nil-tolerant
+  # (+from_api(nil)+ returns +nil+).
+  class StateTaxLegalEntity < Data.define(
+    :federal_tax_number,
+    :name,
+    :trade_name,
+    :tax_regime,
+    :legal_nature,
+    :fiscal_unit,
+    :created_unit,
+    :created_on,
+    :check_code,
+    :state_taxes
+  )
+    # Address nested inside a state-tax registration. Pragmatic subset of the
+    # address fields exposed by the state-tax endpoints.
+    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
+
+    # Economic activity (CNAE) nested inside a state-tax registration.
+    class EconomicActivity < Data.define(:type, :code, :description)
+      def self.from_api(payload)
+        return nil if payload.nil?
+
+        new(
+          type: payload["type"],
+          code: payload["code"]&.to_s,
+          description: payload["description"]
+        )
+      end
+    end
+
+    # Fiscal-document contributor indicator (NFe/NFSe/CTe/NFCe) inside a
+    # state-tax registration.
+    class FiscalDocumentInfo < Data.define(:status, :description)
+      def self.from_api(payload)
+        return nil if payload.nil?
+
+        new(
+          status: payload["status"],
+          description: payload["description"]
+        )
+      end
+    end
+
+    # A single state-tax registration (Inscrição Estadual) within
+    # +stateTaxes+. Carries its own status, dates, code, address and the
+    # per-document contributor indicators.
+    class StateTax < Data.define(
+      :status,
+      :tax_number,
+      :status_on,
+      :opened_on,
+      :closed_on,
+      :additional_information,
+      :code,
+      :address,
+      :economic_activities,
+      :nfe,
+      :nfse,
+      :cte,
+      :nfce
+    )
+      def self.from_api(payload)
+        return nil if payload.nil?
+
+        new(
+          status: payload["status"],
+          tax_number: payload["taxNumber"]&.to_s,
+          status_on: payload["statusOn"],
+          opened_on: payload["openedOn"],
+          closed_on: payload["closedOn"],
+          additional_information: payload["additionalInformation"],
+          code: payload["code"]&.to_s,
+          address: Address.from_api(payload["address"]),
+          economic_activities: (payload["economicActivities"] || []).map { |a| EconomicActivity.from_api(a) },
+          nfe: FiscalDocumentInfo.from_api(payload["nfe"]),
+          nfse: FiscalDocumentInfo.from_api(payload["nfse"]),
+          cte: FiscalDocumentInfo.from_api(payload["cte"]),
+          nfce: FiscalDocumentInfo.from_api(payload["nfce"])
+        )
+      end
+    end
+
+    # @param payload [Hash, nil] the unwrapped +legalEntity+ state-tax object.
+    # @return [Nfe::StateTaxLegalEntity, 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"],
+        tax_regime: payload["taxRegime"],
+        legal_nature: payload["legalNature"],
+        fiscal_unit: payload["fiscalUnit"],
+        created_unit: payload["createdUnit"],
+        created_on: payload["createdOn"],
+        check_code: payload["checkCode"]&.to_s,
+        state_taxes: (payload["stateTaxes"] || []).map { |t| StateTax.from_api(t) }
+      )
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Nfe
+  # Immutable value object for a legal person (pessoa jurídica) tied to a
+  # company. {from_api} maps API camelCase onto snake_case, drops unknown keys,
+  # and is nil-tolerant.
+  #
+  # +federal_tax_number+ is kept as a +String+ (CNPJ), never coerced to Integer.
+  class LegalPerson < Data.define(
+    :id,
+    :name,
+    :trade_name,
+    :federal_tax_number,
+    :email,
+    :address,
+    :created_on,
+    :modified_on
+  )
+    # @param payload [Hash, nil] the unwrapped legal-person object.
+    # @return [Nfe::LegalPerson, 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: payload["federalTaxNumber"]&.to_s,
+        email: payload["email"],
+        address: payload["address"],
+        created_on: payload["createdOn"],
+        modified_on: payload["modifiedOn"]
+      )
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Nfe
+  # Immutable value object for a natural person (pessoa física) tied to a
+  # company. {from_api} maps API camelCase onto snake_case, drops unknown keys,
+  # and is nil-tolerant.
+  #
+  # +federal_tax_number+ is kept as a +String+ (CPF), never coerced to Integer.
+  class NaturalPerson < Data.define(
+    :id,
+    :name,
+    :federal_tax_number,
+    :email,
+    :address,
+    :created_on,
+    :modified_on
+  )
+    # @param payload [Hash, nil] the unwrapped natural-person object.
+    # @return [Nfe::NaturalPerson, nil] +nil+ when +payload+ is +nil+.
+    def self.from_api(payload)
+      return nil if payload.nil?
+
+      new(
+        id: payload["id"],
+        name: payload["name"],
+        federal_tax_number: payload["federalTaxNumber"]&.to_s,
+        email: payload["email"],
+        address: payload["address"],
+        created_on: payload["createdOn"],
+        modified_on: payload["modifiedOn"]
+      )
+    end
+  end
+end

data/lib/nfe/resources/dto/natural_person_lookup/natural_person_status_response.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Nfe
+  # Immutable value object for the result of a natural-person (CPF) status
+  # lookup against the +naturalperson+ data API. {from_api} maps API camelCase
+  # onto snake_case, drops unknown keys, and is nil-tolerant. All fields are
+  # optional.
+  #
+  # +federal_tax_number+ is kept as a +String+ (CPF), never coerced to Integer.
+  class NaturalPersonStatusResponse < Data.define(
+    :name,
+    :federal_tax_number,
+    :birth_on,
+    :status,
+    :created_on
+  )
+    # @param payload [Hash, nil] the unwrapped status object.
+    # @return [Nfe::NaturalPersonStatusResponse, nil] +nil+ when +payload+ is +nil+.
+    def self.from_api(payload)
+      return nil if payload.nil?
+
+      new(
+        name: payload["name"],
+        federal_tax_number: payload["federalTaxNumber"]&.to_s,
+        birth_on: payload["birthOn"],
+        status: payload["status"],
+        created_on: payload["createdOn"]
+      )
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Nfe
+  # Immutable value object describing a downloadable file as returned by the
+  # +api.nfse.io/v2+ product-invoice download endpoints, which respond with a
+  # JSON envelope carrying a +uri+ to the file rather than the raw bytes.
+  #
+  # This is what distinguishes {Nfe::Resources::ProductInvoices} downloads
+  # (which return a +NfeFileResource+) from the byte-returning downloads on the
+  # other invoice resources. {from_api} maps camelCase keys onto snake_case
+  # members, drops unknown keys, and is nil-tolerant.
+  class NfeFileResource < Data.define(:uri, :name, :content_type, :size)
+    # Build a {Nfe::NfeFileResource} from an API payload.
+    #
+    # @param payload [Hash, nil] the response object.
+    # @return [Nfe::NfeFileResource, nil] +nil+ when +payload+ is +nil+.
+    def self.from_api(payload)
+      return nil if payload.nil?
+
+      new(
+        uri: payload["uri"] || payload["url"],
+        name: payload["name"],
+        content_type: payload["contentType"],
+        size: payload["size"]
+      )
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Nfe
+  # Immutable value object for a product invoice (NF-e) as returned by the
+  # NFE.io +api.nfse.io/v2+ product-invoice API.
+  #
+  # Hand-written (rather than reusing the verbose/mangled generated
+  # +nf_produto_v2+ DTO names) so the public shape stays clean and snake_case.
+  # {from_api} maps the API camelCase keys onto snake_case members, drops
+  # unknown keys, and is nil-tolerant (+from_api(nil)+ returns +nil+).
+  #
+  # +flow_status+ drives the polling lifecycle; pass it to
+  # {Nfe::FlowStatus.terminal?} to decide when the document is settled.
+  class ProductInvoice < Data.define(
+    :id,
+    :flow_status,
+    :flow_message,
+    :status,
+    :environment,
+    :serie,
+    :number,
+    :operation_nature,
+    :operation_type,
+    :access_key,
+    :protocol,
+    :buyer,
+    :items,
+    :totals,
+    :issued_on,
+    :created_on,
+    :modified_on
+  )
+    # Build a {Nfe::ProductInvoice} from an API payload.
+    #
+    # @param payload [Hash, nil] the response object.
+    # @return [Nfe::ProductInvoice, nil] +nil+ when +payload+ is +nil+.
+    def self.from_api(payload)
+      return nil if payload.nil?
+
+      new(
+        id: payload["id"],
+        flow_status: payload["flowStatus"],
+        flow_message: payload["flowMessage"],
+        status: payload["status"],
+        environment: payload["environment"],
+        serie: payload["serie"],
+        number: payload["number"],
+        operation_nature: payload["operationNature"],
+        operation_type: payload["operationType"],
+        access_key: payload["accessKey"],
+        protocol: payload["protocol"],
+        buyer: payload["buyer"],
+        items: payload["items"],
+        totals: payload["totals"],
+        issued_on: payload["issuedOn"],
+        created_on: payload["createdOn"],
+        modified_on: payload["modifiedOn"]
+      )
+    end
+  end
+end

data/lib/nfe/resources/dto/product_invoice_query/product_invoice_details.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Nfe
+  # Immutable value object for the details of a product invoice (NF-e) fetched
+  # from the +nfe.api.nfe.io+ distribution/query API by its access key
+  # (+GET /v2/productinvoices/{accessKey}+).
+  #
+  # Hand-written (the +consulta_nfe_distribuicao_v1+ generated schema does not
+  # cover this pragmatic shape). {from_api} maps the API camelCase keys onto the
+  # snake_case members, hydrates the nested value objects, drops unknown keys,
+  # and is nil-tolerant (+from_api(nil)+ returns +nil+). All fields are optional.
+  #
+  # The access key is NOT a body field — it is the path parameter the caller
+  # already holds — so it is intentionally not exposed here. +current_status+ is
+  # the real top-level field (+currentStatus+, enum +unknown+/+authorized+/
+  # +canceled+). The nested objects ({Issuer}, {Buyer}, {Totals}) keep only a
+  # pragmatic subset of the most common fields; +items+ is kept as the raw
+  # payload array (free-form line bodies), normalized to +[]+ when missing.
+  class ProductInvoiceDetails < Data.define(
+    :current_status,
+    :state_code,
+    :check_code,
+    :operation_nature,
+    :serie,
+    :number,
+    :issued_on,
+    :operation_on,
+    :issuer,
+    :buyer,
+    :totals,
+    :items
+  )
+    # Issuer (emitente / emit) of the invoice.
+    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 / dest) of the invoice.
+    class Buyer < Data.define(:federal_tax_number, :name, :state_tax_number, :email)
+      def self.from_api(payload)
+        return nil if payload.nil?
+
+        new(
+          federal_tax_number: payload["federalTaxNumber"]&.to_s,
+          name: payload["name"],
+          state_tax_number: payload["stateTaxNumber"]&.to_s,
+          email: payload["email"]
+        )
+      end
+    end
+
+    # Monetary totals of the invoice (the +icms+ subtotal group of +total+).
+    class Totals < Data.define(:product_amount, :invoice_amount, :discount_amount, :icms_amount)
+      def self.from_api(payload)
+        return nil if payload.nil?
+
+        icms = payload["icms"] || {}
+        new(
+          product_amount: icms["productAmount"],
+          invoice_amount: icms["invoiceAmount"],
+          discount_amount: icms["discountAmount"],
+          icms_amount: icms["icmsAmount"]
+        )
+      end
+    end
+
+    # Build a {Nfe::ProductInvoiceDetails} from an API payload.
+    #
+    # @param payload [Hash, nil] the parsed invoice object.
+    # @return [Nfe::ProductInvoiceDetails, nil] +nil+ when +payload+ is +nil+.
+    def self.from_api(payload)
+      return nil if payload.nil?
+
+      new(
+        current_status: payload["currentStatus"],
+        state_code: payload["stateCode"],
+        check_code: payload["checkCode"]&.to_s,
+        operation_nature: payload["operationNature"],
+        serie: payload["serie"],
+        number: payload["number"],
+        issued_on: payload["issuedOn"],
+        operation_on: payload["operationOn"],
+        issuer: Issuer.from_api(payload["issuer"]),
+        buyer: Buyer.from_api(payload["buyer"]),
+        totals: Totals.from_api(payload["totals"]),
+        items: payload["items"] || []
+      )
+    end
+  end
+end

data/lib/nfe/resources/dto/product_invoice_query/product_invoice_events_response.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Nfe
+  # Immutable value object for the events (eventos) associated with a product
+  # invoice (NF-e), fetched from the +nfe.api.nfe.io+ query API by access key.
+  #
+  # Hand-written (the +consulta_nfe_distribuicao_v1+ generated schema does not
+  # cover this shape). {from_api} maps API camelCase keys onto snake_case
+  # members, drops unknown keys, and is nil-tolerant (+from_api(nil)+ returns
+  # +nil+). All fields are optional.
+  #
+  # +events+ is kept as the raw payload array (free-form event bodies); a
+  # missing list normalizes to +[]+.
+  class ProductInvoiceEventsResponse < Data.define(
+    :events,
+    :created_on
+  )
+    # Build a {Nfe::ProductInvoiceEventsResponse} from an API payload.
+    #
+    # @param payload [Hash, nil] the response object.
+    # @return [Nfe::ProductInvoiceEventsResponse, nil] +nil+ when +payload+ is +nil+.
+    def self.from_api(payload)
+      return nil if payload.nil?
+
+      new(
+        events: payload["events"] || [],
+        created_on: payload["createdOn"]
+      )
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Nfe
+  # Immutable value object for a service invoice (NFS-e) as returned by the
+  # NFE.io +api.nfe.io/v1+ service-invoice API.
+  #
+  # The +nf-servico-v1.yaml+ OpenAPI spec defines NO component schemas (the
+  # shape is derived from the operations), so this DTO is hand-written — mirror
+  # of the fields the Node/PHP SDKs read. {from_api} maps the API camelCase keys
+  # onto snake_case members, drops unknown keys, and is nil-tolerant
+  # (+from_api(nil)+ returns +nil+).
+  #
+  # +flow_status+ drives the polling lifecycle; pass it to
+  # {Nfe::FlowStatus.terminal?} to decide when the document is settled.
+  class ServiceInvoice < Data.define(
+    :id,
+    :flow_status,
+    :flow_message,
+    :status,
+    :environment,
+    :rps_number,
+    :rps_serial_number,
+    :number,
+    :check_code,
+    :issued_on,
+    :cancelled_on,
+    :amount_net,
+    :services_amount,
+    :borrower,
+    :city_service_code,
+    :federal_service_code,
+    :description,
+    :pdf,
+    :xml,
+    :created_on,
+    :modified_on
+  )
+    # Build a {Nfe::ServiceInvoice} from an API payload.
+    #
+    # @param payload [Hash, nil] the response object.
+    # @return [Nfe::ServiceInvoice, nil] +nil+ when +payload+ is +nil+.
+    def self.from_api(payload)
+      return nil if payload.nil?
+
+      new(
+        id: payload["id"],
+        flow_status: payload["flowStatus"],
+        flow_message: payload["flowMessage"],
+        status: payload["status"],
+        environment: payload["environment"],
+        rps_number: payload["rpsNumber"],
+        rps_serial_number: payload["rpsSerialNumber"],
+        number: payload["number"],
+        check_code: payload["checkCode"],
+        issued_on: payload["issuedOn"],
+        cancelled_on: payload["cancelledOn"],
+        amount_net: payload["amountNet"],
+        services_amount: payload["servicesAmount"],
+        borrower: payload["borrower"],
+        city_service_code: payload["cityServiceCode"],
+        federal_service_code: payload["federalServiceCode"],
+        description: payload["description"],
+        pdf: payload["pdf"],
+        xml: payload["xml"],
+        created_on: payload["createdOn"],
+        modified_on: payload["modifiedOn"]
+      )
+    end
+  end
+end

data/lib/nfe/resources/dto/state_taxes/nfe_state_tax.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Nfe
+  # Immutable value object for a company's state-tax (Inscrição Estadual)
+  # registration entry, as returned by the CT-e +api.nfse.io+ state-tax API
+  # under +/v2/companies/{companyId}/statetaxes+.
+  #
+  # Hand-written: the generated +contribuintes-v2+ model lives under a different
+  # namespace/shape, so this top-level {Nfe::NfeStateTax} mirrors only the
+  # fields the Node/PHP SDKs read. {from_api} maps the API camelCase keys onto
+  # snake_case members, drops unknown keys, and is nil-tolerant
+  # (+from_api(nil)+ returns +nil+). All fields are optional.
+  class NfeStateTax < Data.define(
+    :id,
+    :tax_number,
+    :serie,
+    :number,
+    :code,
+    :environment_type,
+    :type,
+    :status
+  )
+    # Build a {Nfe::NfeStateTax} from an API payload.
+    #
+    # @param payload [Hash, nil] the response object.
+    # @return [Nfe::NfeStateTax, nil] +nil+ when +payload+ is +nil+.
+    def self.from_api(payload)
+      return nil if payload.nil?
+
+      new(
+        id: payload["id"],
+        tax_number: payload["taxNumber"],
+        serie: payload["serie"],
+        number: payload["number"],
+        code: payload["code"],
+        environment_type: payload["environmentType"],
+        type: payload["type"],
+        status: payload["status"]
+      )
+    end
+  end
+end

data/lib/nfe/resources/dto/tax_codes/tax_code_paginated_response.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Nfe
+  # A single CT-e tax-code entry (operation code, acquisition purpose, issuer or
+  # recipient tax profile). Hand-written: the +consulta-cte+ tax-code endpoints
+  # are schema-less in the OpenAPI spec, so the generator produces no usable
+  # model. {from_api} maps the API camelCase keys onto snake_case members and is
+  # nil-tolerant (+from_api(nil)+ returns +nil+).
+  class TaxCode < Data.define(:code, :description)
+    # Build a {Nfe::TaxCode} from an API payload.
+    #
+    # @param payload [Hash, nil] the response object.
+    # @return [Nfe::TaxCode, nil] +nil+ when +payload+ is +nil+.
+    def self.from_api(payload)
+      return nil if payload.nil?
+
+      new(
+        code: payload["code"],
+        description: payload["description"]
+      )
+    end
+  end
+
+  # Page-style paginated response for the CT-e tax-code lookup endpoints
+  # (operation code, acquisition purpose, issuer/recipient tax profile).
+  #
+  # NOTE: unlike the cursor-style lists elsewhere in this SDK (which return an
+  # {Nfe::ListResponse} carrying +starting_after+/+ending_before+), these tax-code
+  # endpoints are 1-based page-style, so this resource returns this custom
+  # response object exposing +current_page+/+total_pages+/+total_count+ directly.
+  #
+  # +items+ is hydrated to an Array of {Nfe::TaxCode}. {from_api} is nil-tolerant
+  # (+from_api(nil)+ returns +nil+).
+  class TaxCodePaginatedResponse < Data.define(:current_page, :total_pages, :total_count, :items)
+    # Build a {Nfe::TaxCodePaginatedResponse} from an API payload.
+    #
+    # @param payload [Hash, nil] the response object.
+    # @return [Nfe::TaxCodePaginatedResponse, nil] +nil+ when +payload+ is +nil+.
+    def self.from_api(payload)
+      return nil if payload.nil?
+
+      new(
+        current_page: payload["currentPage"],
+        total_pages: payload["totalPages"],
+        total_count: payload["totalCount"],
+        items: (payload["items"] || []).map { |item| Nfe::TaxCode.from_api(item) }
+      )
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Nfe
+  # Immutable value object for a persisted webhook subscription, as returned by
+  # the +/companies/{id}/webhooks+ entity API.
+  #
+  # NOTE ON NAMING: the spec text refers to this DTO as "Nfe::Webhook", but that
+  # constant is reserved for the canonical signature-verification module
+  # ({Nfe::Webhook}, +lib/nfe/webhook.rb+). A Ruby +module+ and a +class+ cannot
+  # share a constant, so the subscription DTO is named +Nfe::WebhookSubscription+.
+  # Resources hydrating a webhook subscription (+Nfe::Resources::Webhooks+) MUST
+  # hydrate this class.
+  #
+  # {from_api} maps API camelCase onto snake_case, drops unknown keys, and is
+  # nil-tolerant (+from_api(nil)+ returns +nil+).
+  class WebhookSubscription < Data.define(
+    :id,
+    :url,
+    :events,
+    :secret,
+    :active,
+    :status,
+    :created_on,
+    :modified_on
+  )
+    # @param payload [Hash, nil] the unwrapped webhook object.
+    # @return [Nfe::WebhookSubscription, nil] +nil+ when +payload+ is +nil+.
+    def self.from_api(payload)
+      return nil if payload.nil?
+
+      new(
+        id: payload["id"],
+        url: payload["url"],
+        events: payload["events"],
+        secret: payload["secret"],
+        active: payload["active"],
+        status: payload["status"],
+        created_on: payload["createdOn"],
+        modified_on: payload["modifiedOn"]
+      )
+    end
+  end
+end