nfe-io 0.3.2 → 1.0.0

data/lib/nfe/resources/responses/product_invoice_issued.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Nfe
+  module Resources
+    # Result of an immediate (HTTP 201/200) product-invoice (NF-e) emission: the
+    # document was materialized synchronously. +resource+ is the hydrated
+    # {Nfe::ProductInvoice} value object.
+    #
+    # Discriminate against {Nfe::Resources::ProductInvoicePending} with
+    # +pending?+/+issued?+ or +case+ pattern matching.
+    class ProductInvoiceIssued < Data.define(:resource)
+      # @return [false] this is not an async (pending) result.
+      def pending?
+        false
+      end
+
+      # @return [true] this is an immediate (issued) result.
+      def issued?
+        true
+      end
+    end
+  end
+end

data/lib/nfe/resources/responses/product_invoice_pending.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Nfe
+  module Resources
+    # Result of an asynchronous (HTTP 202) product-invoice (NF-e) emission: the
+    # API enqueued the request and is processing it. Completion is notified via
+    # webhook.
+    #
+    # +invoice_id+ is parsed from the +Location+ header's final path segment;
+    # +location+ is the raw header value. Discriminate against
+    # {Nfe::Resources::ProductInvoiceIssued} with +pending?+/+issued?+ or +case+
+    # pattern matching, then poll {Nfe::FlowStatus.terminal?} until settled.
+    class ProductInvoicePending < Data.define(:invoice_id, :location)
+      # @return [true] this is an async (pending) result.
+      def pending?
+        true
+      end
+
+      # @return [false] this is not an immediate (issued) result.
+      def issued?
+        false
+      end
+    end
+  end
+end

data/lib/nfe/resources/responses/product_invoice_rtc_issued.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Nfe
+  module Resources
+    # Result of an immediate (HTTP 201/200) RTC product-invoice (NF-e/NFC-e under
+    # the Reforma Tributária layout) emission: the document was materialized
+    # synchronously. +resource+ is the hydrated
+    # {Nfe::Generated::ProductInvoiceRtcV1::InvoiceResource} value object.
+    #
+    # Discriminate against {Nfe::Resources::ProductInvoiceRtcPending} with
+    # +pending?+/+issued?+ or +case+ pattern matching.
+    class ProductInvoiceRtcIssued < Data.define(:resource)
+      # @return [false] this is not an async (pending) result.
+      def pending?
+        false
+      end
+
+      # @return [true] this is an immediate (issued) result.
+      def issued?
+        true
+      end
+    end
+  end
+end

data/lib/nfe/resources/responses/product_invoice_rtc_pending.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Nfe
+  module Resources
+    # Result of an asynchronous (HTTP 202) RTC product-invoice (NF-e/NFC-e under
+    # the Reforma Tributária layout) emission: the API enqueued the request and
+    # is processing it. Completion is notified via webhook.
+    #
+    # +invoice_id+ is parsed from the +Location+ header's +productinvoices/{id}+
+    # segment; +location+ is the raw header value. Discriminate against
+    # {Nfe::Resources::ProductInvoiceRtcIssued} with +pending?+/+issued?+ or
+    # +case+ pattern matching, then poll {Nfe::FlowStatus.terminal?} until
+    # settled.
+    class ProductInvoiceRtcPending < Data.define(:invoice_id, :location)
+      # @return [true] this is an async (pending) result.
+      def pending?
+        true
+      end
+
+      # @return [false] this is not an immediate (issued) result.
+      def issued?
+        false
+      end
+    end
+  end
+end

data/lib/nfe/resources/responses/service_invoice_issued.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Nfe
+  module Resources
+    # Result of an immediate (HTTP 201/200) service-invoice (NFS-e) emission: the
+    # document was materialized synchronously. +resource+ is the hydrated
+    # {Nfe::ServiceInvoice} value object.
+    #
+    # Discriminate against {Nfe::Resources::ServiceInvoicePending} with
+    # +pending?+/+issued?+ or +case+ pattern matching.
+    class ServiceInvoiceIssued < Data.define(:resource)
+      # @return [false] this is not an async (pending) result.
+      def pending?
+        false
+      end
+
+      # @return [true] this is an immediate (issued) result.
+      def issued?
+        true
+      end
+    end
+  end
+end

data/lib/nfe/resources/responses/service_invoice_pending.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Nfe
+  module Resources
+    # Result of an asynchronous (HTTP 202) service-invoice (NFS-e) emission: 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::Resources::ServiceInvoiceIssued} with +pending?+/+issued?+ or +case+
+    # pattern matching, then poll {Nfe::FlowStatus.terminal?} until settled.
+    class ServiceInvoicePending < Data.define(:invoice_id, :location)
+      # @return [true] this is an async (pending) result.
+      def pending?
+        true
+      end
+
+      # @return [false] this is not an immediate (issued) result.
+      def issued?
+        false
+      end
+    end
+  end
+end

data/lib/nfe/resources/responses/service_invoice_rtc_issued.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Nfe
+  module Resources
+    # Result of an immediate (HTTP 201/200) RTC service-invoice (NFS-e) emission:
+    # the document was materialized synchronously. +resource+ is the hydrated
+    # {Nfe::ServiceInvoice} value object — the RTC create endpoint returns the
+    # standard NFS-e body shape, so the classic hand-written DTO is reused (the
+    # generated +ServiceInvoiceRtcV1::NFSeRequest+ describes only the request).
+    #
+    # Discriminate against {Nfe::Resources::ServiceInvoiceRtcPending} with
+    # +pending?+/+issued?+ or +case+ pattern matching.
+    class ServiceInvoiceRtcIssued < Data.define(:resource)
+      # @return [false] this is not an async (pending) result.
+      def pending?
+        false
+      end
+
+      # @return [true] this is an immediate (issued) result.
+      def issued?
+        true
+      end
+    end
+  end
+end

data/lib/nfe/resources/responses/service_invoice_rtc_pending.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Nfe
+  module Resources
+    # Result of an asynchronous (HTTP 202) RTC service-invoice (NFS-e) emission:
+    # 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::Resources::ServiceInvoiceRtcIssued} with +pending?+/+issued?+ or
+    # +case+ pattern matching, then poll until the document settles.
+    #
+    # RTC and classic NFS-e share the same endpoint; the RTC layout is selected
+    # by the presence of the +ibsCbs+ group in the create payload, so the async
+    # 202 shape is identical to the classic flow.
+    class ServiceInvoiceRtcPending < Data.define(:invoice_id, :location)
+      # @return [true] this is an async (pending) result.
+      def pending?
+        true
+      end
+
+      # @return [false] this is not an immediate (issued) result.
+      def issued?
+        false
+      end
+    end
+  end
+end

data/lib/nfe/resources/service_invoices.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "json"
+require "nfe/resources/abstract_resource"
+require "nfe/resources/dto/service_invoice"
+require "nfe/resources/responses/service_invoice_pending"
+require "nfe/resources/responses/service_invoice_issued"
+
+module Nfe
+  module Resources
+    # Service invoices (NFS-e) resource for the +:main+ host family
+    # (+https://api.nfe.io/v1/...+). This is the canonical emission resource of
+    # the platform.
+    #
+    # Emission is typically asynchronous: {#create} returns either a
+    # {Nfe::Resources::ServiceInvoicePending} (HTTP 202, queued) or a
+    # {Nfe::Resources::ServiceInvoiceIssued} (HTTP 201, materialized). There is
+    # no +create_and_wait+/+create_batch+ in v1.0 — poll manually:
+    #
+    #   result = client.service_invoices.create(company_id: id, data: payload)
+    #   if result.pending?
+    #     loop do
+    #       status = client.service_invoices.get_status(company_id: id, invoice_id: result.invoice_id)
+    #       break if status.complete?
+    #       sleep 2
+    #     end
+    #   end
+    #
+    # @example
+    #   client.service_invoices.create(company_id: "co_1", data: { borrower: {...}, ... })
+    class ServiceInvoices < AbstractResource
+      # Derived status snapshot returned by {ServiceInvoices#get_status} without
+      # issuing an extra HTTP call.
+      class StatusResult < Data.define(:status, :invoice, :complete, :failed)
+        # @return [Boolean] true when the flow status is terminal.
+        def complete?
+          complete
+        end
+
+        # @return [Boolean] true when the flow status is IssueFailed/CancelFailed.
+        def failed?
+          failed
+        end
+      end
+
+      FAILED_STATUSES = %w[IssueFailed CancelFailed].freeze
+
+      protected
+
+      def api_family
+        :main
+      end
+
+      public
+
+      # Create (emit) a service invoice. Returns a discriminated result: a
+      # {ServiceInvoicePending} on HTTP 202 (queued, +invoice_id+ parsed from the
+      # +Location+ header) or a {ServiceInvoiceIssued} on HTTP 201 (materialized).
+      #
+      # @param company_id [String]
+      # @param data [Hash] invoice payload (camelCase keys per the API).
+      # @param idempotency_key [String, nil] sent as the +Idempotency-Key+ header.
+      # @param request_options [Nfe::RequestOptions, nil] per-call overrides.
+      # @return [ServiceInvoicePending, ServiceInvoiceIssued]
+      # @raise [Nfe::InvoiceProcessingError] on a 202 with no/unparsable Location.
+      def create(company_id:, data:, idempotency_key: nil, request_options: nil)
+        cid = Nfe::IdValidator.company_id(company_id)
+        response = post("/companies/#{cid}/serviceinvoices", body: json_body(data),
+                                                             headers: json_headers,
+                                                             idempotency_key: idempotency_key,
+                                                             request_options: request_options)
+        discriminate(response)
+      end
+
+      # List service invoices (page-style pagination plus date filters).
+      #
+      # @param company_id [String]
+      # @param options [Hash] +page_index+, +page_count+, +issued_begin+,
+      #   +issued_end+, +created_begin+, +created_end+, +has_totals+.
+      # @return [Nfe::ListResponse]
+      def list(company_id:, **options)
+        cid = Nfe::IdValidator.company_id(company_id)
+        response = get("/companies/#{cid}/serviceinvoices", query: list_query(options))
+        hydrate_list(Nfe::ServiceInvoice, parse_json(response.body), wrapper_key: "serviceInvoices")
+      end
+
+      # Retrieve a service invoice by id.
+      #
+      # @param company_id [String]
+      # @param invoice_id [String]
+      # @return [Nfe::ServiceInvoice]
+      # @raise [Nfe::NotFoundError] when the API responds 404 or an empty body.
+      def retrieve(company_id:, invoice_id:)
+        cid = Nfe::IdValidator.company_id(company_id)
+        iid = Nfe::IdValidator.invoice_id(invoice_id)
+        response = get("/companies/#{cid}/serviceinvoices/#{iid}")
+        payload = parse_json(response.body)
+        raise Nfe::NotFoundError, "nota de serviço #{iid} não encontrada" if payload.nil?
+
+        hydrate(Nfe::ServiceInvoice, payload)
+      end
+
+      # Cancel a service invoice (synchronous); returns the updated model.
+      #
+      # @param company_id [String]
+      # @param invoice_id [String]
+      # @return [Nfe::ServiceInvoice]
+      def cancel(company_id:, invoice_id:)
+        cid = Nfe::IdValidator.company_id(company_id)
+        iid = Nfe::IdValidator.invoice_id(invoice_id)
+        response = delete("/companies/#{cid}/serviceinvoices/#{iid}")
+        hydrate(Nfe::ServiceInvoice, parse_json(response.body))
+      end
+
+      # E-mail the invoice to the borrower. No e-mail list argument (Node parity).
+      #
+      # @param company_id [String]
+      # @param invoice_id [String]
+      # @return [Hash] +{ sent:, message: }+.
+      def send_email(company_id:, invoice_id:)
+        cid = Nfe::IdValidator.company_id(company_id)
+        iid = Nfe::IdValidator.invoice_id(invoice_id)
+        response = put("/companies/#{cid}/serviceinvoices/#{iid}/sendemail")
+        payload = parse_json(response.body) || {}
+        { sent: payload.fetch("sent", response.success?), message: payload["message"] }
+      end
+
+      # Download the invoice PDF (or the company ZIP when +invoice_id+ is nil).
+      #
+      # @param company_id [String]
+      # @param invoice_id [String, nil]
+      # @return [String] PDF/ZIP bytes (ASCII-8BIT).
+      def download_pdf(company_id:, invoice_id: nil)
+        download_document(company_id: company_id, invoice_id: invoice_id,
+                          ext: "pdf", accept: "application/pdf")
+      end
+
+      # Download the invoice XML (or the company ZIP when +invoice_id+ is nil).
+      #
+      # @param company_id [String]
+      # @param invoice_id [String, nil]
+      # @return [String] XML/ZIP bytes (ASCII-8BIT).
+      def download_xml(company_id:, invoice_id: nil)
+        download_document(company_id: company_id, invoice_id: invoice_id,
+                          ext: "xml", accept: "application/xml")
+      end
+
+      # Status snapshot derived from {#retrieve} (Node parity — no extra HTTP).
+      #
+      # @param company_id [String]
+      # @param invoice_id [String]
+      # @return [StatusResult]
+      def get_status(company_id:, invoice_id:)
+        invoice = retrieve(company_id: company_id, invoice_id: invoice_id)
+        status = invoice&.flow_status || "WaitingSend"
+        StatusResult.new(
+          status: status, invoice: invoice,
+          complete: Nfe::FlowStatus.terminal?(status),
+          failed: FAILED_STATUSES.include?(status)
+        )
+      end
+
+      private
+
+      def json_headers
+        { "Content-Type" => "application/json" }
+      end
+
+      def json_body(data)
+        JSON.generate(data)
+      end
+
+      # Map snake_case list options onto the API's camelCase query parameters,
+      # dropping nil values.
+      def list_query(options)
+        {
+          pageIndex: options[:page_index], pageCount: options[:page_count],
+          issuedBegin: options[:issued_begin], issuedEnd: options[:issued_end],
+          createdBegin: options[:created_begin], createdEnd: options[:created_end],
+          hasTotals: options[:has_totals]
+        }.compact
+      end
+
+      # GET the single-invoice or bulk document path and return binary bytes.
+      def download_document(company_id:, invoice_id:, ext:, accept:)
+        cid = Nfe::IdValidator.company_id(company_id)
+        path = if invoice_id.nil?
+                 "/companies/#{cid}/serviceinvoices/#{ext}"
+               else
+                 iid = Nfe::IdValidator.invoice_id(invoice_id)
+                 "/companies/#{cid}/serviceinvoices/#{iid}/#{ext}"
+               end
+        download(path, headers: { "Accept" => accept })
+      end
+
+      # Interpret the emission response into the discriminated value object.
+      def discriminate(response)
+        return build_pending(response) if response.status == 202
+
+        ServiceInvoiceIssued.new(resource: hydrate(Nfe::ServiceInvoice, parse_json(response.body)))
+      end
+
+      # Build a {ServiceInvoicePending} from a 202 response, or raise when the
+      # Location header is missing/unparsable.
+      def build_pending(response)
+        location = response.location
+        invoice_id = extract_invoice_id(location)
+        if location.nil? || location.empty? || invoice_id.nil?
+          raise Nfe::InvoiceProcessingError.new(
+            "Resposta 202 sem Location utilizável: não é possível identificar a NFS-e em processamento.",
+            status_code: response.status, response_headers: response.headers
+          )
+        end
+        ServiceInvoicePending.new(invoice_id: invoice_id, location: location)
+      end
+
+      # Extract the trailing id from a +Location+ path.
+      def extract_invoice_id(location)
+        return nil if location.nil?
+
+        match = location.match(%r{serviceinvoices/([a-z0-9-]+)}i)
+        match ? match[1] : nil
+      end
+    end
+  end
+end

data/lib/nfe/resources/service_invoices_rtc.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "json"
+require "nfe/resources/abstract_resource"
+require "nfe/resources/dto/service_invoice"
+require "nfe/resources/responses/service_invoice_rtc_pending"
+require "nfe/resources/responses/service_invoice_rtc_issued"
+
+module Nfe
+  module Resources
+    # RTC (Reforma Tributária do Consumo) service-invoice (NFS-e) emission
+    # resource for the +:main+ host family (+https://api.nfe.io/v1/...+).
+    #
+    # RTC reuses the SAME endpoints as the classic {Nfe::Resources::ServiceInvoices}
+    # resource (+/companies/{company_id}/serviceinvoices+). There is no
+    # discriminator header or query parameter: the API selects the RTC document
+    # layout from the PRESENCE of the +ibsCbs+ group in the create payload. When
+    # +ibsCbs+ is absent the API falls back to the classic NFS-e layout.
+    #
+    # Emission is typically asynchronous: {#create} returns either a
+    # {Nfe::Resources::ServiceInvoiceRtcPending} (HTTP 202, queued) or a
+    # {Nfe::Resources::ServiceInvoiceRtcIssued} (HTTP 201, materialized). There is
+    # no +create_and_wait+/+create_batch+ — poll {#retrieve} manually.
+    #
+    # @example RTC emission selected by the +ibsCbs+ group
+    #   client.service_invoices_rtc.create(
+    #     company_id: "co_1",
+    #     data: { borrower: { ... }, servicesAmount: 100.0, ibsCbs: { cbs: { ... }, ibs: { ... } } }
+    #   )
+    class ServiceInvoicesRtc < AbstractResource
+      protected
+
+      def api_family
+        :main
+      end
+
+      def api_version
+        "v1"
+      end
+
+      public
+
+      # Create (emit) an RTC service invoice. Returns a discriminated result: a
+      # {ServiceInvoiceRtcPending} on HTTP 202 (queued, +invoice_id+ parsed from
+      # the +Location+ header) or a {ServiceInvoiceRtcIssued} on HTTP 201
+      # (materialized, hydrating {Nfe::ServiceInvoice}).
+      #
+      # +data+ is a Hash with camelCase keys (JSON-encoded as-is). The generated
+      # +Nfe::Generated::ServiceInvoiceRtcV1::NFSeRequest+ DTO documents the
+      # expected payload SHAPE (including the nested +ibsCbs+, +borrower+,
+      # +location+, ... groups), but is NOT accepted as input: the generated DTOs
+      # deserialize only (+from_api+) and have no camelCase re-serializer, so
+      # passing the object would emit wrong keys. The RTC layout is selected by
+      # the presence of the +ibsCbs+ group in +data+ — same endpoint as the
+      # classic resource, no discriminator header/param.
+      #
+      # @param company_id [String]
+      # @param data [Hash] invoice payload (camelCase keys); include +ibsCbs+ to
+      #   select the RTC layout. Mirrors +ServiceInvoiceRtcV1::NFSeRequest+.
+      # @param idempotency_key [String, nil] sent as the +Idempotency-Key+ header.
+      # @param request_options [Nfe::RequestOptions, nil] per-call overrides.
+      # @return [ServiceInvoiceRtcPending, ServiceInvoiceRtcIssued]
+      # @raise [Nfe::InvoiceProcessingError] on a 202 with no/unparsable Location.
+      def create(company_id:, data:, idempotency_key: nil, request_options: nil)
+        cid = Nfe::IdValidator.company_id(company_id)
+        response = post("/companies/#{cid}/serviceinvoices", body: json_body(data),
+                                                             headers: json_headers,
+                                                             idempotency_key: idempotency_key,
+                                                             request_options: request_options)
+        discriminate(response)
+      end
+
+      # Retrieve an RTC service invoice by id. The 201/GET body is the standard
+      # NFS-e shape, hydrated into {Nfe::ServiceInvoice}.
+      #
+      # @param company_id [String]
+      # @param invoice_id [String]
+      # @return [Nfe::ServiceInvoice]
+      # @raise [Nfe::NotFoundError] when the API responds 404 or an empty body.
+      def retrieve(company_id:, invoice_id:)
+        cid = Nfe::IdValidator.company_id(company_id)
+        iid = Nfe::IdValidator.invoice_id(invoice_id)
+        response = get("/companies/#{cid}/serviceinvoices/#{iid}")
+        payload = parse_json(response.body)
+        raise Nfe::NotFoundError, "nota de serviço #{iid} não encontrada" if payload.nil?
+
+        hydrate(Nfe::ServiceInvoice, payload)
+      end
+
+      # Cancel an RTC service invoice (synchronous); returns the updated model.
+      #
+      # @param company_id [String]
+      # @param invoice_id [String]
+      # @return [Nfe::ServiceInvoice]
+      def cancel(company_id:, invoice_id:)
+        cid = Nfe::IdValidator.company_id(company_id)
+        iid = Nfe::IdValidator.invoice_id(invoice_id)
+        response = delete("/companies/#{cid}/serviceinvoices/#{iid}")
+        hydrate(Nfe::ServiceInvoice, parse_json(response.body))
+      end
+
+      # Download the cancellation XML (ADN-only, available after the invoice
+      # reaches the +Cancelled+ state). Returns the raw bytes (+ASCII-8BIT+).
+      #
+      # @param company_id [String]
+      # @param invoice_id [String]
+      # @return [String] XML bytes (ASCII-8BIT).
+      # @raise [Nfe::NotFoundError] when the document is unavailable (404/empty).
+      def download_cancellation_xml(company_id:, invoice_id:)
+        cid = Nfe::IdValidator.company_id(company_id)
+        iid = Nfe::IdValidator.invoice_id(invoice_id)
+        bytes = download("/companies/#{cid}/serviceinvoices/#{iid}/cancellation-xml",
+                         headers: { "Accept" => "application/xml" })
+        raise Nfe::NotFoundError, "XML de cancelamento da nota #{iid} não encontrado" if bytes.empty?
+
+        bytes
+      end
+
+      private
+
+      def json_headers
+        { "Content-Type" => "application/json" }
+      end
+
+      def json_body(data)
+        JSON.generate(data)
+      end
+
+      # Interpret the emission response into the discriminated value object.
+      def discriminate(response)
+        return build_pending(response) if response.status == 202
+
+        ServiceInvoiceRtcIssued.new(resource: hydrate(Nfe::ServiceInvoice, parse_json(response.body)))
+      end
+
+      # Build a {ServiceInvoiceRtcPending} from a 202 response, or raise when the
+      # Location header is missing/unparsable.
+      def build_pending(response)
+        location = response.location
+        invoice_id = extract_rtc_invoice_id(location)
+        if location.nil? || location.empty? || invoice_id.nil?
+          raise Nfe::InvoiceProcessingError.new(
+            "Resposta 202 sem Location utilizável: não é possível identificar a NFS-e em processamento.",
+            status_code: response.status, response_headers: response.headers
+          )
+        end
+        ServiceInvoiceRtcPending.new(invoice_id: invoice_id, location: location)
+      end
+
+      # Extract the trailing id from a +Location+ path.
+      def extract_rtc_invoice_id(location)
+        return nil if location.nil?
+
+        match = location.match(%r{serviceinvoices/([a-z0-9-]+)}i)
+        match ? match[1] : nil
+      end
+    end
+  end
+end