nfe-io 0.3.2 → 1.0.0

data/lib/nfe/resources/state_taxes.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "json"
+require "nfe/resources/abstract_resource"
+require "nfe/resources/dto/state_taxes/nfe_state_tax"
+
+module Nfe
+  module Resources
+    # Company state-tax (Inscrição Estadual) registrations for the +:cte+ host
+    # family (+https://api.nfse.io/v2/companies/{companyId}/statetaxes+). Exposes
+    # the full CRUD: list (cursor-style), create, retrieve, update and delete.
+    #
+    # The API wraps single state-tax objects in a +{"stateTax" => <object>}+
+    # envelope (and the list in +{"stateTaxes" => [...]}+), transparently
+    # unwrapped here before hydrating {Nfe::NfeStateTax}.
+    #
+    # @example
+    #   client.state_taxes.create(company_id, code: "SP", taxNumber: "1234567890")
+    #   client.state_taxes.list(company_id, limit: 50)
+    class StateTaxes < AbstractResource
+      # Envelope key for a single state-tax object.
+      ENVELOPE = "stateTax"
+      # Wrapper key for the list envelope.
+      LIST_ENVELOPE = "stateTaxes"
+
+      protected
+
+      def api_family
+        :cte
+      end
+
+      # The +:cte+ host (+api.nfse.io+) does not bake in a version; the +/v2+
+      # segment is carried in the base path instead.
+      def api_version
+        ""
+      end
+
+      public
+
+      # List a company's state-tax registrations (cursor-style pagination).
+      #
+      # @param company_id [String]
+      # @param starting_after [String, nil] cursor — items after this id.
+      # @param ending_before [String, nil] cursor — items before this id.
+      # @param limit [Integer, nil] page size.
+      # @return [Nfe::ListResponse]
+      def list(company_id, starting_after: nil, ending_before: nil, limit: nil)
+        cid = Nfe::IdValidator.company_id(company_id)
+        query = {} #: Hash[String, untyped]
+        query["startingAfter"] = starting_after unless starting_after.nil?
+        query["endingBefore"] = ending_before unless ending_before.nil?
+        query["limit"] = limit unless limit.nil?
+        response = get(base_path(cid), query: query)
+        hydrate_list(Nfe::NfeStateTax, parse_json(response.body), wrapper_key: LIST_ENVELOPE)
+      end
+
+      # Create a state-tax registration.
+      #
+      # @param company_id [String]
+      # @param data [Hash] state-tax attributes (camelCase keys per the API).
+      # @return [Nfe::NfeStateTax]
+      def create(company_id, data)
+        cid = Nfe::IdValidator.company_id(company_id)
+        response = post(base_path(cid), body: JSON.generate({ ENVELOPE => data }),
+                                        headers: json_headers)
+        hydrate(Nfe::NfeStateTax, unwrap(parse_json(response.body), ENVELOPE))
+      end
+
+      # Retrieve a single state-tax registration.
+      #
+      # @param company_id [String]
+      # @param state_tax_id [String]
+      # @return [Nfe::NfeStateTax]
+      def retrieve(company_id, state_tax_id)
+        cid = Nfe::IdValidator.company_id(company_id)
+        sid = Nfe::IdValidator.state_tax_id(state_tax_id)
+        response = get("#{base_path(cid)}/#{sid}")
+        hydrate(Nfe::NfeStateTax, unwrap(parse_json(response.body), ENVELOPE))
+      end
+
+      # Update a state-tax registration.
+      #
+      # @param company_id [String]
+      # @param state_tax_id [String]
+      # @param data [Hash] state-tax attributes (camelCase keys per the API).
+      # @return [Nfe::NfeStateTax]
+      def update(company_id, state_tax_id, data)
+        cid = Nfe::IdValidator.company_id(company_id)
+        sid = Nfe::IdValidator.state_tax_id(state_tax_id)
+        response = put("#{base_path(cid)}/#{sid}", body: JSON.generate({ ENVELOPE => data }),
+                                                   headers: json_headers)
+        hydrate(Nfe::NfeStateTax, unwrap(parse_json(response.body), ENVELOPE))
+      end
+
+      # Delete a state-tax registration.
+      #
+      # @param company_id [String]
+      # @param state_tax_id [String]
+      # @return [nil]
+      def delete(company_id, state_tax_id)
+        cid = Nfe::IdValidator.company_id(company_id)
+        sid = Nfe::IdValidator.state_tax_id(state_tax_id)
+        super("#{base_path(cid)}/#{sid}")
+        nil
+      end
+
+      private
+
+      def base_path(company_id)
+        "/v2/companies/#{company_id}/statetaxes"
+      end
+
+      def json_headers
+        { "Content-Type" => "application/json" }
+      end
+    end
+  end
+end

data/lib/nfe/resources/tax_calculation.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "json"
+require "nfe/resources/abstract_resource"
+require "nfe/generated/calculo_impostos_v1/cofins"
+require "nfe/generated/calculo_impostos_v1/icms"
+require "nfe/generated/calculo_impostos_v1/icms_uf_dest"
+require "nfe/generated/calculo_impostos_v1/ii"
+require "nfe/generated/calculo_impostos_v1/ipi"
+require "nfe/generated/calculo_impostos_v1/pis"
+require "nfe/generated/calculo_impostos_v1/calculate_item_response"
+require "nfe/generated/calculo_impostos_v1/calculate_response"
+
+module Nfe
+  module Resources
+    # Tax calculation engine for the +:cte+ family (host +api.nfse.io+). Runs the
+    # tax rules engine for a tenant and returns a per-item tax breakdown.
+    class TaxCalculation < AbstractResource
+      protected
+
+      def api_family = :cte
+
+      # The path already carries its own segments, so no version prefix is added.
+      def api_version = ""
+
+      public
+
+      # Run the tax-rules engine for +tenant_id+ over +request+.
+      #
+      # Client-side validation runs FIRST (no HTTP when invalid): +tenant_id+
+      # must be non-empty and +request+ must be a Hash carrying +operation_type+
+      # (or +operationType+) plus a non-empty +items+ Array.
+      #
+      # +request+ accepts a plain Hash. For type-safety you may build it from
+      # {Nfe::Generated::CalculoImpostosV1::CalculateRequest#to_h}.
+      #
+      # @param tenant_id [String] the tenant identifier (URL-encoded into the path).
+      # @param request [Hash] the calculation request body.
+      # @return [Nfe::Generated::CalculoImpostosV1::CalculateResponse]
+      def calculate(tenant_id, request)
+        validate_calculate!(tenant_id, request)
+        path = "/tax-rules/#{CGI.escape(tenant_id.to_s.strip)}/engine/calculate"
+        response = post(path, body: JSON.generate(request),
+                              headers: { "Content-Type" => "application/json" })
+        hydrate(Nfe::Generated::CalculoImpostosV1::CalculateResponse, parse_json(response.body))
+      end
+
+      private
+
+      # Fail fast (no HTTP) when the tenant or request shape is invalid.
+      def validate_calculate!(tenant_id, request)
+        Nfe::IdValidator.presence!(tenant_id, "tenant_id")
+        return if request.is_a?(Hash) && operation_type?(request) && items?(request)
+
+        raise Nfe::InvalidRequestError,
+              "request deve conter operation_type (ou operationType) e items (Array não vazio)"
+      end
+
+      def operation_type?(request)
+        !request[:operation_type].nil? || !request["operation_type"].nil? ||
+          !request[:operationType].nil? || !request["operationType"].nil?
+      end
+
+      def items?(request)
+        items = request[:items] || request["items"]
+        items.is_a?(Array) && !items.empty?
+      end
+    end
+  end
+end

data/lib/nfe/resources/tax_codes.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "nfe/resources/abstract_resource"
+require "nfe/resources/dto/tax_codes/tax_code_paginated_response"
+
+module Nfe
+  module Resources
+    # CT-e tax-code lookup tables for the +:cte+ host family
+    # (+https://api.nfse.io/tax-codes/...+). Exposes the four reference lists
+    # consumed when building a CT-e: operation codes, acquisition purposes, and
+    # the issuer/recipient tax profiles.
+    #
+    # These endpoints paginate page-style (1-based +pageIndex+/+pageCount+), so
+    # every method returns an {Nfe::TaxCodePaginatedResponse} (NOT an
+    # {Nfe::ListResponse}); see that class for why this differs from the
+    # cursor-style lists elsewhere in the SDK.
+    #
+    # @example
+    #   client.tax_codes.list_operation_codes(page_index: 2, page_count: 20)
+    class TaxCodes < AbstractResource
+      protected
+
+      def api_family
+        :cte
+      end
+
+      # The +:cte+ host (+api.nfse.io+) does not bake in a version and these
+      # tax-code paths carry none, so no version segment is prefixed.
+      def api_version
+        ""
+      end
+
+      public
+
+      # List CT-e operation codes (Código de Operação).
+      #
+      # @param page_index [Integer, nil] 1-based page index (preserved as given).
+      # @param page_count [Integer, nil] page size.
+      # @return [Nfe::TaxCodePaginatedResponse]
+      def list_operation_codes(page_index: nil, page_count: nil)
+        list_tax_codes("/tax-codes/operation-code", page_index, page_count)
+      end
+
+      # List CT-e acquisition purposes (Finalidade de Aquisição).
+      #
+      # @param page_index [Integer, nil] 1-based page index (preserved as given).
+      # @param page_count [Integer, nil] page size.
+      # @return [Nfe::TaxCodePaginatedResponse]
+      def list_acquisition_purposes(page_index: nil, page_count: nil)
+        list_tax_codes("/tax-codes/acquisition-purpose", page_index, page_count)
+      end
+
+      # List CT-e issuer tax profiles (Perfil Tributário do Emitente).
+      #
+      # @param page_index [Integer, nil] 1-based page index (preserved as given).
+      # @param page_count [Integer, nil] page size.
+      # @return [Nfe::TaxCodePaginatedResponse]
+      def list_issuer_tax_profiles(page_index: nil, page_count: nil)
+        list_tax_codes("/tax-codes/issuer-tax-profile", page_index, page_count)
+      end
+
+      # List CT-e recipient tax profiles (Perfil Tributário do Destinatário).
+      #
+      # @param page_index [Integer, nil] 1-based page index (preserved as given).
+      # @param page_count [Integer, nil] page size.
+      # @return [Nfe::TaxCodePaginatedResponse]
+      def list_recipient_tax_profiles(page_index: nil, page_count: nil)
+        list_tax_codes("/tax-codes/recipient-tax-profile", page_index, page_count)
+      end
+
+      private
+
+      # Shared GET + page-style query builder for the four tax-code endpoints.
+      # Only the non-nil paging parameters are sent, keeping them out of the URL
+      # when omitted.
+      def list_tax_codes(path, page_index, page_count)
+        query = {} #: Hash[String, untyped]
+        query["pageIndex"] = page_index unless page_index.nil?
+        query["pageCount"] = page_count unless page_count.nil?
+        response = get(path, query: query)
+        hydrate(Nfe::TaxCodePaginatedResponse, parse_json(response.body))
+      end
+    end
+  end
+end

data/lib/nfe/resources/transportation_invoices.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "json"
+require "nfe/resources/abstract_resource"
+require "nfe/resources/dto/inbound_settings"
+require "nfe/resources/dto/inbound_invoice_metadata"
+
+module Nfe
+  module Resources
+    # Inbound CT-e (Conhecimento de Transporte Eletrônico) resource for the
+    # +:cte+ host family (+https://api.nfse.io+). Manages automatic CT-e fetch
+    # via SEFAZ Distribuição DFe and reads received CT-e documents/events by
+    # 44-digit access key.
+    #
+    # This is an inbound/query resource (settings + access-key lookups), not an
+    # emission resource: there is no discriminated 202 +Pending+/+Issued+
+    # contract here. The host already carries no version segment, so paths embed
+    # +/v2+ literally and {#api_version} is +""+.
+    #
+    # @example Enable auto-fetch and read a received CT-e
+    #   client.transportation_invoices.enable(company_id: "co-1")
+    #   cte = client.transportation_invoices.retrieve(
+    #     company_id: "co-1",
+    #     access_key: "3524...7890"
+    #   )
+    class TransportationInvoices < AbstractResource
+      protected
+
+      def api_family
+        :cte
+      end
+
+      # The +:cte+ host carries no version segment; +/v2+ is embedded per path.
+      def api_version
+        ""
+      end
+
+      public
+
+      # Enable automatic CT-e search for a company via Distribuição DFe.
+      #
+      # @param company_id [String]
+      # @param start_from_nsu [Integer, String, nil] optional starting NSU.
+      # @param start_from_date [String, nil] optional starting date (ISO 8601).
+      # @return [Nfe::InboundSettings]
+      def enable(company_id:, start_from_nsu: nil, start_from_date: nil)
+        id = Nfe::IdValidator.company_id(company_id)
+        body = compact("startFromNsu" => start_from_nsu, "startFromDate" => start_from_date)
+        response = post("/v2/companies/#{id}/inbound/transportationinvoices",
+                        body: json_body(body), headers: json_headers)
+        hydrate(Nfe::InboundSettings, parse_json(response.body))
+      end
+
+      # Disable automatic CT-e search for a company.
+      #
+      # @param company_id [String]
+      # @return [Nfe::InboundSettings]
+      def disable(company_id:)
+        id = Nfe::IdValidator.company_id(company_id)
+        response = delete("/v2/companies/#{id}/inbound/transportationinvoices")
+        hydrate(Nfe::InboundSettings, parse_json(response.body))
+      end
+
+      # Get the current automatic CT-e search settings.
+      #
+      # @param company_id [String]
+      # @return [Nfe::InboundSettings]
+      def get_settings(company_id:)
+        id = Nfe::IdValidator.company_id(company_id)
+        response = get("/v2/companies/#{id}/inbound/transportationinvoices")
+        hydrate(Nfe::InboundSettings, parse_json(response.body))
+      end
+
+      # Retrieve CT-e metadata by its 44-digit access key (normalized).
+      #
+      # @param company_id [String]
+      # @param access_key [String] 44-digit key; separators are stripped.
+      # @return [Nfe::InboundInvoiceMetadata]
+      def retrieve(company_id:, access_key:)
+        id = Nfe::IdValidator.company_id(company_id)
+        key = Nfe::IdValidator.access_key(access_key)
+        response = get("/v2/companies/#{id}/inbound/#{key}")
+        hydrate(Nfe::InboundInvoiceMetadata, parse_json(response.body))
+      end
+
+      # Download the CT-e XML by access key.
+      #
+      # @param company_id [String]
+      # @param access_key [String]
+      # @return [String] raw XML bytes (+ASCII-8BIT+).
+      def download_xml(company_id:, access_key:)
+        id = Nfe::IdValidator.company_id(company_id)
+        key = Nfe::IdValidator.access_key(access_key)
+        download("/v2/companies/#{id}/inbound/#{key}/xml", headers: xml_accept)
+      end
+
+      # Retrieve the metadata of an event related to a received CT-e.
+      #
+      # @param company_id [String]
+      # @param access_key [String]
+      # @param event_key [String]
+      # @return [Nfe::InboundInvoiceMetadata]
+      def get_event(company_id:, access_key:, event_key:)
+        id = Nfe::IdValidator.company_id(company_id)
+        key = Nfe::IdValidator.access_key(access_key)
+        ev = Nfe::IdValidator.event_key(event_key)
+        response = get("/v2/companies/#{id}/inbound/#{key}/events/#{ev}")
+        hydrate(Nfe::InboundInvoiceMetadata, parse_json(response.body))
+      end
+
+      # Download the XML of a CT-e event.
+      #
+      # @param company_id [String]
+      # @param access_key [String]
+      # @param event_key [String]
+      # @return [String] raw XML bytes (+ASCII-8BIT+).
+      def download_event_xml(company_id:, access_key:, event_key:)
+        id = Nfe::IdValidator.company_id(company_id)
+        key = Nfe::IdValidator.access_key(access_key)
+        ev = Nfe::IdValidator.event_key(event_key)
+        download("/v2/companies/#{id}/inbound/#{key}/events/#{ev}/xml", headers: xml_accept)
+      end
+
+      private
+
+      def json_headers
+        { "Content-Type" => "application/json" }
+      end
+
+      def json_body(data)
+        JSON.generate(data)
+      end
+
+      def xml_accept
+        { "Accept" => "application/xml" }
+      end
+
+      # Drop +nil+ values so optional fields are omitted from the body.
+      def compact(hash)
+        hash.compact
+      end
+    end
+  end
+end

data/lib/nfe/resources/webhooks.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "json"
+require "nfe/resources/abstract_resource"
+require "nfe/resources/dto/webhook"
+require "nfe/webhook"
+
+module Nfe
+  module Resources
+    # Webhooks resource, company-scoped under +/companies/{id}/webhooks+ on the
+    # +:main+ host family. Exposes CRUD, a synthetic-delivery +test+, the static
+    # list of available events, and a thin {#verify_signature} delegation to
+    # {Nfe::Webhook} (the canonical signature-verification API is the module).
+    class Webhooks < AbstractResource
+      # The seven event types the NFE.io API can deliver (parity with Node).
+      AVAILABLE_EVENTS = %w[
+        invoice.issued
+        invoice.cancelled
+        invoice.failed
+        invoice.processing
+        company.created
+        company.updated
+        company.deleted
+      ].freeze
+
+      protected
+
+      def api_family
+        :main
+      end
+
+      public
+
+      # List a company's webhook subscriptions.
+      #
+      # @param company_id [String]
+      # @return [Nfe::ListResponse]
+      def list(company_id)
+        id = Nfe::IdValidator.company_id(company_id)
+        response = get("/companies/#{id}/webhooks")
+        payload = parse_json(response.body)
+        items = webhook_items(payload).map { |item| hydrate(Nfe::WebhookSubscription, item) }
+        Nfe::ListResponse.new(data: items)
+      end
+
+      # Create a webhook subscription. Accepts +url+, +events+, +secret+, +active+.
+      #
+      # @param company_id [String]
+      # @param data [Hash]
+      # @return [Nfe::Webhook]
+      def create(company_id, data)
+        id = Nfe::IdValidator.company_id(company_id)
+        response = post("/companies/#{id}/webhooks",
+                        body: json_body(data), headers: json_headers)
+        hydrate(Nfe::WebhookSubscription, parse_json(response.body))
+      end
+
+      # Retrieve a webhook by id.
+      #
+      # @param company_id [String]
+      # @param webhook_id [String]
+      # @return [Nfe::Webhook]
+      def retrieve(company_id, webhook_id)
+        id = Nfe::IdValidator.company_id(company_id)
+        wid = Nfe::IdValidator.presence!(webhook_id, "webhook_id")
+        response = get("/companies/#{id}/webhooks/#{wid}")
+        hydrate(Nfe::WebhookSubscription, parse_json(response.body))
+      end
+
+      # Update a webhook.
+      #
+      # @param company_id [String]
+      # @param webhook_id [String]
+      # @param data [Hash]
+      # @return [Nfe::Webhook]
+      def update(company_id, webhook_id, data)
+        id = Nfe::IdValidator.company_id(company_id)
+        wid = Nfe::IdValidator.presence!(webhook_id, "webhook_id")
+        response = put("/companies/#{id}/webhooks/#{wid}",
+                       body: json_body(data), headers: json_headers)
+        hydrate(Nfe::WebhookSubscription, parse_json(response.body))
+      end
+
+      # Delete a webhook.
+      #
+      # @param company_id [String]
+      # @param webhook_id [String]
+      # @return [nil]
+      def delete(company_id, webhook_id)
+        id = Nfe::IdValidator.company_id(company_id)
+        wid = Nfe::IdValidator.presence!(webhook_id, "webhook_id")
+        super("/companies/#{id}/webhooks/#{wid}")
+        nil
+      end
+
+      # Trigger a synthetic delivery to verify a webhook is reachable.
+      #
+      # @param company_id [String]
+      # @param webhook_id [String]
+      # @return [Hash] +{ success: bool, message: String? }+.
+      def test(company_id, webhook_id)
+        id = Nfe::IdValidator.company_id(company_id)
+        wid = Nfe::IdValidator.presence!(webhook_id, "webhook_id")
+        response = post("/companies/#{id}/webhooks/#{wid}/test",
+                        body: json_body({}), headers: json_headers)
+        payload = parse_json(response.body) || {}
+        { success: payload["success"] || false, message: payload["message"] }
+      end
+
+      # The static list of webhook event types the API can deliver.
+      #
+      # @return [Array<String>]
+      def get_available_events
+        AVAILABLE_EVENTS.dup
+      end
+
+      # Verify a webhook signature. Thin delegation to {Nfe::Webhook} for Node
+      # parity; the canonical API is the module. Never raises.
+      #
+      # @return [Boolean]
+      def verify_signature(payload:, signature:, secret:)
+        Nfe::Webhook.verify_signature(payload: payload, signature: signature, secret: secret)
+      end
+
+      private
+
+      def json_headers
+        { "Content-Type" => "application/json" }
+      end
+
+      def json_body(data)
+        JSON.generate(data)
+      end
+
+      # Tolerate either a bare array, a +data+-wrapped list, or a +webhooks+
+      # envelope for the list response.
+      def webhook_items(payload)
+        return payload if payload.is_a?(Array)
+        return [] unless payload.is_a?(Hash)
+
+        payload["data"] || payload["webhooks"] || payload[:data] || payload[:webhooks] || []
+      end
+    end
+  end
+end

data/lib/nfe/results.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Nfe
+  # Result of an asynchronous (HTTP 202) invoice operation: the API accepted
+  # the request and is processing it. The document is not yet materialized.
+  #
+  # +invoice_id+ is parsed from the +Location+ header's final path segment;
+  # +location+ is the raw header value. Discriminate against {Nfe::Issued} with
+  # +is_a?+/+case+ and poll {Nfe::FlowStatus.terminal?} until settled.
+  class Pending < Data.define(:invoice_id, :location)
+  end
+
+  # Result of a synchronous (HTTP 201/200) invoice operation: the document was
+  # materialized immediately. +resource+ is the hydrated DTO value object.
+  class Issued < Data.define(:resource)
+  end
+end

data/lib/nfe/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Nfe
-  VERSION = "0.3.2"
+  VERSION = "1.0.0"
 end