nfe-io 0.3.1 → 1.0.0

data/lib/nfe/resources/companies.rb

@@ -0,0 +1,349 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "nfe/resources/abstract_resource"
+require "nfe/resources/dto/company"
+require "nfe/certificate"
+
+module Nfe
+  module Resources
+    # Companies resource for the +:main+ host family
+    # (+https://api.nfe.io/v1/...+). Exposes the company CRUD plus the digital
+    # certificate lifecycle (upload/replace/validate/status) and convenience
+    # finders. The NFE.io API wraps company responses in a
+    # +{"companies" => <object|array>}+ envelope, transparently unwrapped here
+    # before hydrating {Nfe::Company}.
+    #
+    # @example
+    #   company = client.companies.create(name: "Acme", federalTaxNumber: "12345678000199")
+    #   client.companies.retrieve(company.id)
+    class Companies < AbstractResource
+      ENVELOPE = "companies"
+
+      protected
+
+      def api_family
+        :main
+      end
+
+      public
+
+      # Create a company. Validates +federalTaxNumber+ format (11/14 digits,
+      # never coerced to Integer) and e-mail format when present.
+      #
+      # @param data [Hash] company attributes (camelCase keys per the API).
+      # @return [Nfe::Company]
+      def create(data)
+        validate_company_data(data)
+        response = post("/companies", body: json_body(data), headers: json_headers)
+        hydrate(Nfe::Company, unwrap(parse_json(response.body), ENVELOPE))
+      end
+
+      # List one page of companies. The public +page_index+ is 0-based and is
+      # sent to the API as its 1-based +pageIndex+ (which must be >= 1); the
+      # 1-based +page+ in the response is converted back to 0-based.
+      #
+      # @param page_index [Integer] 0-based page index.
+      # @param page_count [Integer] page size.
+      # @return [Nfe::ListResponse]
+      def list(page_index: 0, page_count: 100)
+        response = get("/companies", query: { pageIndex: page_index + 1, pageCount: page_count })
+        payload = parse_json(response.body) || {}
+        items = (unwrap(payload, ENVELOPE) || []).map { |item| hydrate(Nfe::Company, item) }
+        resolved_index = resolve_page_index(payload, page_index)
+        Nfe::ListResponse.new(
+          data: items,
+          page: Nfe::ListPage.from_page(page_index: resolved_index, page_count: page_count)
+        )
+      end
+
+      # Fetch every company by auto-paginating with +page_count: 100+ until a
+      # short page is returned. Convenience helper; not optimized for large
+      # accounts.
+      #
+      # @return [Array<Nfe::Company>]
+      def list_all
+        list_each.to_a
+      end
+
+      # Stream companies lazily, one per +yield+, fetching pages on demand.
+      # Convenience helper; not optimized for large accounts.
+      #
+      # @return [Enumerator<Nfe::Company>]
+      def list_each
+        Enumerator.new do |yielder|
+          page_index = 0
+          loop do
+            page = list(page_index: page_index, page_count: 100)
+            page.data.each { |company| yielder << company }
+            break if page.data.length < 100
+
+            page_index += 1
+          end
+        end
+      end
+
+      # Retrieve a company by id.
+      #
+      # @param company_id [String]
+      # @return [Nfe::Company]
+      # @raise [Nfe::NotFoundError] when the API responds 404.
+      def retrieve(company_id)
+        id = Nfe::IdValidator.company_id(company_id)
+        response = get("/companies/#{id}")
+        hydrate(Nfe::Company, unwrap(parse_json(response.body), ENVELOPE))
+      end
+
+      # Update a company.
+      #
+      # @param company_id [String]
+      # @param data [Hash]
+      # @return [Nfe::Company]
+      def update(company_id, data)
+        id = Nfe::IdValidator.company_id(company_id)
+        validate_company_data(data)
+        response = put("/companies/#{id}", body: json_body(data), headers: json_headers)
+        hydrate(Nfe::Company, unwrap(parse_json(response.body), ENVELOPE))
+      end
+
+      # Delete a company. Named +remove+ to avoid clashing with +delete+
+      # semantics (parity with the Node/PHP SDKs).
+      #
+      # @param company_id [String]
+      # @return [Hash] +{ deleted: true, id: company_id }+.
+      def remove(company_id)
+        id = Nfe::IdValidator.company_id(company_id)
+        delete("/companies/#{id}")
+        { deleted: true, id: id }
+      end
+
+      # Find a company by federal tax number (CNPJ/CPF). Convenience helper built
+      # on {#list_all} plus client-side filtering; not optimized for large
+      # accounts.
+      #
+      # @param tax_number [String, Integer]
+      # @return [Nfe::Company, nil]
+      def find_by_tax_number(tax_number)
+        normalized = normalize_tax_number(tax_number)
+        list_each.find { |company| normalize_tax_number(company.federal_tax_number) == normalized }
+      end
+
+      # Find companies whose name contains +name+ (case-insensitive). Convenience
+      # helper built on {#list_all}; not optimized for large accounts.
+      #
+      # @param name [String]
+      # @return [Array<Nfe::Company>]
+      def find_by_name(name)
+        term = name.to_s.strip
+        raise Nfe::InvalidRequestError, "nome de busca (name) não pode ser vazio" if term.empty?
+
+        term = term.downcase
+        list_all.select { |company| company.name.to_s.downcase.include?(term) }
+      end
+
+      # Validate a PKCS#12 certificate locally (no HTTP) and extract its
+      # metadata. The password and bytes are handled in-memory only.
+      #
+      # @param file [String] a file path or the raw .pfx/.p12 bytes.
+      # @param password [String]
+      # @return [Nfe::CertificateInfo]
+      # @raise [Nfe::InvalidRequestError] on wrong password or malformed DER.
+      def validate_certificate(file:, password:)
+        Nfe::CertificateValidator.validate(read_certificate_bytes(file), password)
+      end
+
+      # Upload a digital certificate, pre-validating it locally (fail-fast)
+      # before POSTing a +multipart/form-data+ body to
+      # +/companies/{id}/certificate+ with the +file+ and +password+ fields.
+      #
+      # @param company_id [String]
+      # @param file [String] file path or raw bytes.
+      # @param password [String]
+      # @param filename [String, nil] used for the extension check and part name.
+      # @return [Hash] +{ uploaded: bool, message: String? }+.
+      def upload_certificate(company_id, file:, password:, filename: nil)
+        id = Nfe::IdValidator.company_id(company_id)
+        if filename && !Nfe::CertificateValidator.supported_format?(filename)
+          raise Nfe::InvalidRequestError,
+                "formato de certificado não suportado: apenas .pfx e .p12 são aceitos"
+        end
+
+        bytes = read_certificate_bytes(file)
+        Nfe::CertificateValidator.validate(bytes, password) # fail-fast, raises on invalid
+
+        response = upload_multipart(
+          "/companies/#{id}/certificate",
+          "file" => { filename: filename || "certificate.pfx",
+                      content: bytes, content_type: "application/x-pkcs12" },
+          "password" => password
+        )
+        payload = parse_json(response.body) || {}
+        { uploaded: true, message: payload["message"] }
+      end
+
+      # Replace an existing certificate. Alias of {#upload_certificate} — the API
+      # handles replacement.
+      #
+      # @see #upload_certificate
+      def replace_certificate(company_id, file:, password:, filename: nil)
+        upload_certificate(company_id, file: file, password: password, filename: filename)
+      end
+
+      # Fetch certificate status, computing +days_until_expiration+ and
+      # +expiring_soon+ client-side from +expires_on+ when present.
+      #
+      # @param company_id [String]
+      # @return [Nfe::CertificateStatus]
+      def get_certificate_status(company_id)
+        id = Nfe::IdValidator.company_id(company_id)
+        response = get("/companies/#{id}/certificate")
+        details = parse_json(response.body) || {}
+        build_certificate_status(details)
+      end
+
+      # Return an expiry warning when the certificate expires within
+      # +threshold_days+, otherwise +nil+.
+      #
+      # @param company_id [String]
+      # @param threshold_days [Integer]
+      # @return [Hash, nil] +{ expiring: true, days_remaining:, expires_on: }+.
+      def check_certificate_expiration(company_id, threshold_days: 30)
+        status = get_certificate_status(company_id)
+        return nil unless status.has_certificate && status.expires_on
+
+        days = status.days_until_expiration
+        return nil if days.nil?
+
+        return unless days >= 0 && days < threshold_days
+
+        { expiring: true, days_remaining: days, expires_on: status.expires_on }
+      end
+
+      # List companies that have a valid certificate. Convenience helper:
+      # {#list_all} + one +get_certificate_status+ per company (companies whose
+      # status lookup fails are skipped).
+      #
+      # @return [Array<Nfe::Company>]
+      def get_companies_with_certificates
+        list_all.select do |company|
+          status = certificate_status_or_nil(company.id.to_s)
+          status&.has_certificate && status.valid
+        end
+      end
+
+      # List companies whose certificate expires within +threshold_days+.
+      # Convenience helper; companies whose status lookup fails are skipped.
+      #
+      # @param threshold_days [Integer]
+      # @return [Array<Nfe::Company>]
+      def get_companies_with_expiring_certificates(threshold_days: 30)
+        list_all.select do |company|
+          expiring_or_nil(company.id.to_s, threshold_days)
+        end
+      end
+
+      private
+
+      def json_headers
+        { "Content-Type" => "application/json" }
+      end
+
+      def json_body(data)
+        JSON.generate(data)
+      end
+
+      # API uses 1-based +page+; convert to 0-based, falling back to the
+      # requested index when the API omits it.
+      def resolve_page_index(payload, requested_index)
+        api_page = payload["page"] || payload[:page]
+        return requested_index if api_page.nil?
+
+        api_page - 1
+      end
+
+      # Validate +federalTaxNumber+ format/length and e-mail without coercing to
+      # Integer or running check-digit rules (design D12). Tolerant of both
+      # camelCase and snake_case keys.
+      def validate_company_data(data)
+        tax = data[:federalTaxNumber] || data["federalTaxNumber"] ||
+              data[:federal_tax_number] || data["federal_tax_number"]
+        unless tax.nil?
+          digits = normalize_tax_number(tax)
+          unless [11, 14].include?(digits.length)
+            raise Nfe::InvalidRequestError,
+                  "federalTaxNumber deve conter 11 dígitos (CPF) ou 14 (CNPJ)"
+          end
+        end
+
+        email = data[:email] || data["email"]
+        return if email.nil?
+        return if valid_email?(email.to_s)
+
+        raise Nfe::InvalidRequestError, "e-mail (email) com formato inválido"
+      end
+
+      # Structural e-mail check without a backtracking-prone regex (avoids the
+      # polynomial ReDoS in +[^\s@]+@[^\s@]+\.[^\s@]++). Equivalent semantics:
+      # exactly one "@", no whitespace, and a dotted domain with non-empty
+      # leading/trailing labels. Every step is linear in the input length.
+      def valid_email?(value)
+        return false if value.match?(/\s/)
+
+        local, separator, domain = value.partition("@")
+        return false if separator.empty? || local.empty? || domain.empty?
+        return false if domain.include?("@")
+        return false if domain.start_with?(".") || domain.end_with?(".")
+
+        domain.include?(".")
+      end
+
+      def normalize_tax_number(value)
+        value.to_s.gsub(/[^0-9A-Za-z]/, "")
+      end
+
+      # Read certificate bytes from a file path or accept raw bytes verbatim.
+      # Raw PKCS#12 (DER) bytes contain NUL bytes, which would make +File.file?+
+      # raise "path name contains null byte" — so a value with a NUL byte is
+      # always treated as content, and the path check runs only on NUL-free
+      # strings (which cannot trigger that error).
+      def read_certificate_bytes(file)
+        bytes = file.to_s.dup.force_encoding(Encoding::ASCII_8BIT)
+        return File.binread(file) if file.is_a?(String) && !bytes.include?("\x00".b) && File.file?(file)
+
+        bytes
+      end
+
+      def build_certificate_status(details)
+        has_certificate = details["hasCertificate"] || details["has_certificate"] || false
+        expires_on = details["expiresOn"] || details["expires_on"]
+        valid = details.key?("isValid") ? details["isValid"] : details["valid"]
+
+        days = nil
+        expiring = nil
+        if has_certificate && expires_on
+          not_after = Time.parse(expires_on.to_s)
+          days = Nfe::CertificateValidator.days_until_expiration(not_after)
+          expiring = Nfe::CertificateValidator.expiring_soon?(not_after)
+        end
+
+        Nfe::CertificateStatus.new(
+          has_certificate: has_certificate, expires_on: expires_on, valid: valid,
+          days_until_expiration: days, expiring_soon: expiring, details: details
+        )
+      end
+
+      def certificate_status_or_nil(company_id)
+        get_certificate_status(company_id)
+      rescue Nfe::Error
+        nil
+      end
+
+      def expiring_or_nil(company_id, threshold_days)
+        check_certificate_expiration(company_id, threshold_days: threshold_days)
+      rescue Nfe::Error
+        nil
+      end
+    end
+  end
+end

data/lib/nfe/resources/consumer_invoice_query.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "nfe/resources/abstract_resource"
+require "nfe/resources/dto/consumer_invoice_query/tax_coupon"
+
+module Nfe
+  module Resources
+    # Query (consulta) of consumer invoices — NFC-e tax coupons (CFe-SAT) — by
+    # access key, served by the +:nfe_query+ family (+nfe.api.nfe.io+, +/v1+,
+    # +/coupon/+ path).
+    #
+    # This is DISTINCT from {Nfe::Resources::ConsumerInvoices} (NFC-e emission,
+    # +add-invoice-resources+): different host and API version. Here we only
+    # retrieve and download an already-issued coupon.
+    class ConsumerInvoiceQuery < AbstractResource
+      protected
+
+      def api_family = :nfe_query
+
+      # The version segment (+v1+) is embedded in the request path, so no version
+      # prefix is added by the base class.
+      def api_version = ""
+
+      public
+
+      # Retrieve a consumer-invoice tax coupon by its access key.
+      #
+      # @param access_key [String] the 44-digit NFC-e access key (normalized).
+      # @return [Nfe::TaxCoupon]
+      def retrieve(access_key)
+        key = Nfe::IdValidator.access_key(access_key)
+        hydrate(Nfe::TaxCoupon, parse_json(get("/v1/consumerinvoices/coupon/#{key}").body))
+      end
+
+      # Download the raw XML for a consumer-invoice tax coupon.
+      #
+      # @param access_key [String] the 44-digit NFC-e access key (normalized).
+      # @return [String] the XML document bytes (+ASCII-8BIT+).
+      def download_xml(access_key)
+        key = Nfe::IdValidator.access_key(access_key)
+        download("/v1/consumerinvoices/coupon/#{key}.xml", headers: { "Accept" => "application/xml" })
+      end
+    end
+  end
+end

data/lib/nfe/resources/consumer_invoices.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require "json"
+require "nfe/resources/abstract_resource"
+require "nfe/resources/dto/consumer_invoice"
+require "nfe/resources/responses/consumer_invoice_pending"
+require "nfe/resources/responses/consumer_invoice_issued"
+
+module Nfe
+  module Resources
+    # Consumer invoices (NFC-e — Nota Fiscal de Consumidor Eletrônica).
+    #
+    # Hosted at +https://api.nfse.io+ under +/v2+ (the +:cte+ family), backed by
+    # the paths exposed in +nf-consumidor-v2.yaml+.
+    #
+    # == Parity-plus
+    # This resource is a *parity-plus* addition: the Node.js SDK deliberately
+    # does NOT expose NFC-e emission (it covers only the read-only
+    # +consumerInvoiceQuery+). The NFE.io API has supported the full NFC-e
+    # lifecycle since v2, so this Ruby SDK extends beyond Node parity — useful
+    # for PoS and e-commerce integrations.
+    #
+    # == Intentional omissions (grounded in Brazilian fiscal law)
+    # Unlike {Nfe::Resources::ProductInvoices} (NF-e), this resource does NOT
+    # define:
+    # * +send_correction_letter+ — the Carta de Correção Eletrônica (CC-e)
+    #   instrument applies only to NF-e/CT-e, never to NFC-e.
+    # * +download_epec_xml+ — there is no EPEC (Evento Prévio de Emissão em
+    #   Contingência) for NFC-e.
+    # * a per-invoice +disable+ — NFC-e supports only *collective* inutilization
+    #   of a number range via {#disable_range}, not per-document disablement.
+    # Calling any of these raises +NoMethodError+.
+    #
+    # == Emission contract
+    # {#create} and {#create_with_state_tax} return a discriminated result:
+    # {Nfe::Resources::ConsumerInvoicePending} on HTTP 202 (async) or
+    # {Nfe::Resources::ConsumerInvoiceIssued} on HTTP 201/200 (sync). Both accept
+    # an optional +idempotency_key:+ (sent as the +Idempotency-Key+ header; the
+    # SDK never auto-retries, so re-invoking with the SAME key after a timeout
+    # lets the server deduplicate) and +request_options:+ (per-call
+    # multi-tenant overrides). +create_and_wait+/+create_batch+ are deferred:
+    # poll manually with +result.pending?+ + {Nfe::FlowStatus.terminal?}.
+    #
+    # @example Emit an NFC-e and handle the discriminated result
+    #   result = client.consumer_invoices.create(company_id: id, data: payload)
+    #   case result
+    #   in Nfe::Resources::ConsumerInvoicePending => p then poll(p.invoice_id)
+    #   in Nfe::Resources::ConsumerInvoiceIssued  => i then i.resource
+    #   end
+    class ConsumerInvoices < AbstractResource
+      # Wrapper key for the list envelope.
+      ENVELOPE = "consumerInvoices"
+
+      protected
+
+      def api_family
+        :cte
+      end
+
+      # The +:cte+ host (+api.nfse.io+) does not bake in a version, so this
+      # resource supplies the +/v2+ segment itself.
+      def api_version
+        "v2"
+      end
+
+      public
+
+      # Emit an NFC-e. Returns {ConsumerInvoicePending} (HTTP 202) or
+      # {ConsumerInvoiceIssued} (HTTP 201/200).
+      #
+      # @param company_id [String]
+      # @param data [Hash] NFC-e payload (camelCase keys per the API).
+      # @param idempotency_key [String, nil] sent as +Idempotency-Key+.
+      # @param request_options [Nfe::RequestOptions, nil] per-call overrides.
+      # @return [ConsumerInvoicePending, ConsumerInvoiceIssued]
+      def create(company_id:, data:, idempotency_key: nil, request_options: nil)
+        id = Nfe::IdValidator.company_id(company_id)
+        response = post("/companies/#{id}/consumerinvoices", body: json_body(data),
+                                                             headers: json_headers,
+                                                             idempotency_key: idempotency_key,
+                                                             request_options: request_options)
+        discriminate(response)
+      end
+
+      # Emit an NFC-e scoped to a specific state-tax registration.
+      #
+      # @param company_id [String]
+      # @param state_tax_id [String]
+      # @param data [Hash]
+      # @param idempotency_key [String, nil]
+      # @param request_options [Nfe::RequestOptions, nil]
+      # @return [ConsumerInvoicePending, ConsumerInvoiceIssued]
+      def create_with_state_tax(company_id:, state_tax_id:, data:, idempotency_key: nil, request_options: nil)
+        cid = Nfe::IdValidator.company_id(company_id)
+        sid = Nfe::IdValidator.state_tax_id(state_tax_id)
+        response = post("/companies/#{cid}/statetaxes/#{sid}/consumerinvoices",
+                        body: json_body(data), headers: json_headers,
+                        idempotency_key: idempotency_key, request_options: request_options)
+        discriminate(response)
+      end
+
+      # List NFC-e for a company (cursor pagination; wrapper +consumerInvoices+).
+      #
+      # @param company_id [String]
+      # @param options [Hash] cursor query params (+starting_after+, +limit+...).
+      # @return [Nfe::ListResponse]
+      def list(company_id:, environment:, **options)
+        id = Nfe::IdValidator.company_id(company_id)
+        require_environment(environment)
+        response = get("/companies/#{id}/consumerinvoices",
+                       query: options.merge(environment: environment))
+        hydrate_list(Nfe::ConsumerInvoice, parse_json(response.body), wrapper_key: ENVELOPE)
+      end
+
+      # Retrieve a single NFC-e by id.
+      #
+      # @return [Nfe::ConsumerInvoice]
+      def retrieve(company_id:, invoice_id:)
+        cid, iid = validate_pair(company_id, invoice_id)
+        response = get("/companies/#{cid}/consumerinvoices/#{iid}")
+        hydrate(Nfe::ConsumerInvoice, parse_json(response.body))
+      end
+
+      # Cancel an NFC-e (synchronous); returns the updated model.
+      #
+      # @return [Nfe::ConsumerInvoice]
+      def cancel(company_id:, invoice_id:)
+        cid, iid = validate_pair(company_id, invoice_id)
+        response = delete("/companies/#{cid}/consumerinvoices/#{iid}")
+        hydrate(Nfe::ConsumerInvoice, parse_json(response.body))
+      end
+
+      # List the line items of an NFC-e.
+      #
+      # @return [Array<Hash>]
+      def list_items(company_id:, invoice_id:)
+        cid, iid = validate_pair(company_id, invoice_id)
+        response = get("/companies/#{cid}/consumerinvoices/#{iid}/items")
+        unwrap_collection(parse_json(response.body), "items")
+      end
+
+      # List the events of an NFC-e.
+      #
+      # @return [Array<Hash>]
+      def list_events(company_id:, invoice_id:)
+        cid, iid = validate_pair(company_id, invoice_id)
+        response = get("/companies/#{cid}/consumerinvoices/#{iid}/events")
+        unwrap_collection(parse_json(response.body), "events")
+      end
+
+      # Download the DANFE NFC-e PDF as binary bytes (unlike ProductInvoices,
+      # which returns a URI).
+      #
+      # @return [String] +ASCII-8BIT+ PDF bytes.
+      def download_pdf(company_id:, invoice_id:)
+        cid, iid = validate_pair(company_id, invoice_id)
+        download("/companies/#{cid}/consumerinvoices/#{iid}/pdf",
+                 headers: { "Accept" => "application/pdf" })
+      end
+
+      # Download the authorized NFC-e XML as binary bytes.
+      #
+      # @return [String] +ASCII-8BIT+ XML bytes.
+      def download_xml(company_id:, invoice_id:)
+        cid, iid = validate_pair(company_id, invoice_id)
+        download("/companies/#{cid}/consumerinvoices/#{iid}/xml",
+                 headers: { "Accept" => "application/xml" })
+      end
+
+      # Download the rejection XML (sefaz refusal) as binary bytes.
+      #
+      # @return [String] +ASCII-8BIT+ XML bytes.
+      def download_rejection_xml(company_id:, invoice_id:)
+        cid, iid = validate_pair(company_id, invoice_id)
+        download("/companies/#{cid}/consumerinvoices/#{iid}/xml/rejection",
+                 headers: { "Accept" => "application/xml" })
+      end
+
+      # Collectively inutilize a range of NFC-e numbers. NFC-e supports only
+      # collective inutilization (no per-invoice disablement).
+      #
+      # @param company_id [String]
+      # @param data [Hash] +{ environment, serie, state, begin_number, last_number, reason? }+.
+      # @return [Hash] the parsed disablement result.
+      def disable_range(company_id:, data:)
+        id = Nfe::IdValidator.company_id(company_id)
+        response = post("/companies/#{id}/consumerinvoices/disablement",
+                        body: json_body(data), headers: json_headers)
+        parse_json(response.body) || {}
+      end
+
+      private
+
+      # The API rejects a NFC-e listing without an +environment+; require it
+      # client-side (mirrors product_invoices#list).
+      def require_environment(environment)
+        return unless environment.nil? || environment.to_s.strip.empty?
+
+        raise Nfe::InvalidRequestError, "environment é obrigatório (Production ou Test)"
+      end
+
+      # Validate a (company_id, invoice_id) pair, returning both normalized.
+      def validate_pair(company_id, invoice_id)
+        [Nfe::IdValidator.company_id(company_id), Nfe::IdValidator.invoice_id(invoice_id)]
+      end
+
+      # Interpret an emission response into the discriminated NFC-e result.
+      def discriminate(response)
+        return issued_result(response) unless response.status == 202
+
+        location = response.location
+        if location.nil? || location.empty?
+          raise Nfe::InvoiceProcessingError.new(
+            "Resposta 202 sem cabeçalho Location: não é possível identificar a NFC-e em processamento.",
+            status_code: response.status, response_headers: response.headers
+          )
+        end
+        ConsumerInvoicePending.new(invoice_id: extract_invoice_id(location), location: location)
+      end
+
+      def issued_result(response)
+        invoice = hydrate(Nfe::ConsumerInvoice, parse_json(response.body))
+        ConsumerInvoiceIssued.new(resource: invoice)
+      end
+
+      # Extract the trailing id from a +Location+ path.
+      def extract_invoice_id(location)
+        match = location.match(%r{/([a-z0-9-]+)\z}i)
+        match ? match[1] : nil
+      end
+
+      # Unwrap a collection envelope, tolerating a bare array or a wrapped one.
+      def unwrap_collection(payload, key)
+        return payload if payload.is_a?(Array)
+        return [] unless payload.is_a?(Hash)
+
+        wrapped = payload[key] || payload[key.to_sym]
+        wrapped.is_a?(Array) ? wrapped : []
+      end
+
+      def json_headers
+        { "Content-Type" => "application/json" }
+      end
+
+      def json_body(data)
+        JSON.generate(data)
+      end
+    end
+  end
+end