corvo-nfse 0.1.1

data/lib/corvo_nfse/transport.rb

@@ -0,0 +1,302 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "openssl"
+
+module CorvoNfse
+  # Thin synchronous HTTP layer over +Net::HTTP+ (keep-alive).
+  #
+  # Every resource routes through here. It never raises for API, network, or
+  # timeout failures — those come back as ``[nil, error]``. Two envelope helpers
+  # live here: ``unwrap`` (modes ``data`` / ``none``) and
+  # ``to_error`` (non-2xx -> CorvoApiError).
+  class Transport
+    DEFAULT_PREFIX = "v1"
+    DEFAULT_TIMEOUT = 30
+
+    attr_reader :base_url
+
+    def initialize(api_key:, base_url:, prefix: DEFAULT_PREFIX, timeout: DEFAULT_TIMEOUT)
+      @api_key = api_key
+      root = base_url.to_s.sub(%r{/+\z}, "")
+      cleaned = (prefix || "").to_s.gsub(%r{\A/+|/+\z}, "")
+      @base_url = cleaned.empty? ? root : "#{root}/#{cleaned}"
+      @timeout = timeout
+
+      root_uri = URI.parse(root)
+      @http = Net::HTTP.new(root_uri.host, root_uri.port)
+      @http.use_ssl = root_uri.scheme == "https"
+      @http.open_timeout = timeout
+      @http.read_timeout = timeout
+      @http.write_timeout = timeout if @http.respond_to?(:write_timeout=)
+    end
+
+    # Returns ``[data, error]``. +type+ is an optional Types:: data class the
+    # unwrapped payload is mapped onto.
+    def request(method, path, json: nil, query: nil, idempotency_key: nil, unwrap: "data", type: nil)
+      uri = build_uri(path, query)
+      req = request_class(method).new(uri)
+      apply_headers(req, idempotency_key)
+      if json
+        req["Content-Type"] = "application/json"
+        req.body = JSON.generate(json)
+      end
+      res, error = perform(req)
+      return [nil, error] if error
+
+      data, herror = handle_response(res, unwrap)
+      return [nil, herror] if herror
+
+      [map_type(data, type), nil]
+    end
+
+    # Multipart upload. The SDK passes +fields+ to +set_form+, which sets the
+    # ``multipart/form-data`` Content-Type (with boundary) itself — we never set
+    # it manually.
+    def request_form(method, path, fields, unwrap: "data", type: nil)
+      uri = build_uri(path, nil)
+      req = request_class(method).new(uri)
+      apply_headers(req, nil)
+      boundary = "----CorvoFormBoundary#{rand(0x100000000).to_s(16)}"
+      req.body = encode_multipart(fields, boundary)
+      req["Content-Type"] = "multipart/form-data; boundary=#{boundary}"
+      res, error = perform(req)
+      return [nil, error] if error
+
+      data, herror = handle_response(res, unwrap)
+      return [nil, herror] if herror
+
+      [map_type(data, type), nil]
+    end
+
+    # RFC 7578 multipart body: a `file` part (with filename + content type) and
+    # plain text parts, matching the canonical Node SDK's wire shape.
+    def encode_multipart(fields, boundary)
+      body = +""
+      fields.each do |field|
+        body << "--#{boundary}\r\n"
+        if field.length == 4
+          name, content, content_type, filename = field
+          body << %(Content-Disposition: form-data; name="#{name}"; filename="#{filename}"\r\n)
+          body << "Content-Type: #{content_type}\r\n\r\n"
+          body << content.to_s
+          body << "\r\n"
+        else
+          name, content = field
+          body << %(Content-Disposition: form-data; name="#{name}"\r\n\r\n)
+          body << content.to_s
+          body << "\r\n"
+        end
+      end
+      body << "--#{boundary}--\r\n"
+      body
+    end
+
+    # Binary download: returns a Types::DownloadedFile.
+    def request_raw(method, path, query: nil)
+      uri = build_uri(path, query)
+      req = request_class(method).new(uri)
+      apply_headers(req, nil)
+      res, error = perform(req)
+      return [nil, error] if error
+
+      status = res.code.to_i
+      return [nil, nil] if status == 204
+      return [nil, to_error(res)] unless (200..299).cover?(status)
+
+      disposition = res["Content-Disposition"]
+      file_name = disposition && disposition[/filename="([^"]+)"/, 1]
+      [
+        Types::DownloadedFile.new(
+          content: res.body.to_s.b,
+          mime_type: res["Content-Type"],
+          file_name: file_name
+        ),
+        nil
+      ]
+    end
+
+    # One list page as a Types::Paginated (``{ data, pagination }``).
+    def list_page(path, query = nil, mapper: nil)
+      raw, error = request("GET", path, query: query, unwrap: "none")
+      return [nil, error] if error
+
+      body = raw.is_a?(Hash) ? raw : {}
+      items = body["data"]
+      items = items.is_a?(Array) ? items : []
+      items = items.map { |item| mapper.call(item) } if mapper
+      pagination = body["pagination"]
+      pag = pagination.is_a?(Hash) ? Types::Pagination.from_wire(pagination) : nil
+      [Types::Paginated.new(data: items, pagination: pag), nil]
+    end
+
+    # Walk cursor pages, yielding every item. Without a block returns an
+    # Enumerator.
+    #
+    # The one place in the SDK that raises: a first-page (or any-page) failure
+    # raises CorvoApiError instead of returning a tuple, because an
+    # Enumerator/block has no result slot for it.
+    def iterate(path, query = nil, mapper: nil)
+      unless block_given?
+        return Enumerator.new do |yielder|
+          iterate(path, query, mapper: mapper) { |item| yielder << item }
+        end
+      end
+
+      base_query = (query || {}).dup
+      cursor = base_query[:cursor]
+      loop do
+        page_query = base_query.merge(cursor: cursor)
+        page, error = list_page(path, page_query, mapper: mapper)
+        raise error if error
+
+        page.data.each { |item| yield item }
+        pag = page.pagination
+        return unless pag && pag.hasMore
+
+        cursor = pag.nextCursor
+        return if cursor.nil?
+      end
+    end
+
+    # Map a non-2xx response to a typed error (see shared spec).
+    def to_error(res)
+      status = res.code.to_i
+      body = {}
+      if res["Content-Type"].to_s.start_with?("application/json")
+        begin
+          parsed = JSON.parse(res.body.to_s)
+          body = parsed if parsed.is_a?(Hash)
+        rescue JSON::ParserError
+          body = {}
+        end
+      end
+
+      code = body["code"].is_a?(String) && !body["code"].empty? ? body["code"] : "http_#{status}"
+      raw_message = body["message"]
+      message =
+        if raw_message.is_a?(String)
+          raw_message
+        elsif raw_message.is_a?(Array)
+          raw_message.map(&:to_s).join("; ")
+        elsif body["error"].is_a?(String)
+          body["error"]
+        else
+          "Request failed with status #{status}"
+        end
+      details = body["details"].is_a?(Array) ? body["details"] : []
+      request_id = body["requestId"] || res["X-Request-Id"]
+
+      retry_after = body["retryAfter"]
+      if retry_after.is_a?(Numeric)
+        retry_after = retry_after.to_i
+      else
+        header = res["Retry-After"]
+        retry_after = header && header.match?(/\A-?\d+\z/) ? header.to_i : nil
+      end
+
+      CorvoApiError.new(
+        status: status,
+        code: code,
+        message: message,
+        details: details,
+        request_id: request_id,
+        retry_after: retry_after
+      )
+    end
+
+    private
+
+    def build_uri(path, query)
+      uri = URI.parse("#{@base_url}#{path}")
+      params = (query || {}).compact
+      uri.query = URI.encode_www_form(params) unless params.empty?
+      uri
+    end
+
+    def request_class(method)
+      case method.to_s.upcase
+      when "GET" then Net::HTTP::Get
+      when "POST" then Net::HTTP::Post
+      when "PATCH" then Net::HTTP::Patch
+      when "PUT" then Net::HTTP::Put
+      when "DELETE" then Net::HTTP::Delete
+      else
+        raise ArgumentError, "Unsupported HTTP method: #{method}"
+      end
+    end
+
+    def apply_headers(req, idempotency_key)
+      req["X-API-Key"] = @api_key
+      req["Accept"] = "application/json"
+      req["Idempotency-Key"] = idempotency_key if idempotency_key
+    end
+
+    def handle_response(res, unwrap_mode)
+      status = res.code.to_i
+      return [nil, nil] if status == 204
+      return [nil, to_error(res)] unless (200..299).cover?(status)
+
+      body = res.body.to_s
+      return [nil, nil] if body.empty?
+
+      begin
+        parsed = JSON.parse(body)
+      rescue JSON::ParserError
+        return [nil, invalid_json_error(status, res)]
+      end
+      [unwrap(parsed, unwrap_mode), nil]
+    end
+
+    def invalid_json_error(status, res)
+      CorvoApiError.new(
+        status: status,
+        code: "invalid_json",
+        message: "Invalid JSON in response",
+        details: [],
+        request_id: res["X-Request-Id"]
+      )
+    end
+
+    def unwrap(value, mode)
+      return value if mode == "none"
+
+      value.is_a?(Hash) ? value["data"] : nil
+    end
+
+    def map_type(data, type)
+      return data unless type
+
+      data.nil? ? nil : type.from_wire(data)
+    end
+
+    def perform(req)
+      [@http.request(req), nil]
+    rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout => e
+      [nil, timeout_error(e)]
+    rescue SocketError, EOFError, IOError, OpenSSL::SSL::SSLError,
+           Net::HTTPBadResponse, SystemCallError => e
+      [nil, network_error(e)]
+    end
+
+    def timeout_error(e)
+      CorvoApiError.new(
+        status: 0,
+        code: "timeout",
+        message: "Request timed out after #{@timeout}s: #{e}",
+        details: []
+      )
+    end
+
+    def network_error(e)
+      CorvoApiError.new(
+        status: 0,
+        code: "network_error",
+        message: "Network request failed: #{e}",
+        details: []
+      )
+    end
+  end
+end

data/lib/corvo_nfse/types/billing.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module CorvoNfse
+  module Types
+    # ``GET /billing/plan`` payload. The nested +plan+, +subscription+ and
+    # +usage+ objects use snake_case wire keys and are returned as raw wire
+    # hashes under those members (pass-through, never re-cased).
+    BillingPlanResponse = define_data(:plan, :subscription, :usage)
+
+    # ``GET /billing/usage`` payload (camelCase wire keys).
+    QuotaStatus = define_data(
+      :canEmit, :creditsRemaining, :creditsUsed, :creditsReserved,
+      :monthlyAllowance, :dailyUsage, :dailyLimit, :activeCompanies,
+      :maxActiveCompanies, :periodStart, :periodEnd, :reason
+    )
+  end
+end

data/lib/corvo_nfse/types/certificate.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module CorvoNfse
+  module Types
+    # A stored A1/A3 signing certificate (PKCS#12) for a company.
+    Certificate = define_data(
+      :id, :companyId, :serialNumber, :issuer, :subject, :fingerprint,
+      :validFrom, :validUntil, :status, :createdAt
+    )
+  end
+end

data/lib/corvo_nfse/types/common.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module CorvoNfse
+  module Types
+    # Pagination cursor metadata returned by every list endpoint.
+    Pagination = define_data(:limit, :hasMore, :nextCursor)
+
+    # A single list page: +data+ items plus +pagination+ metadata.
+    Paginated = define_data(:data, :pagination)
+
+    # Binary payload from ``/invoices/:id/pdf|xml``. This one is SDK-side (not a
+    # wire envelope), hence the snake_case members.
+    DownloadedFile = define_data(:content, :mime_type, :file_name)
+  end
+end

data/lib/corvo_nfse/types/company.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module CorvoNfse
+  module Types
+    # A fiscal company (the invoice issuer) registered with Corvo. Optional fields
+    # are absent from the JSON when unset and read as nil. +setupGaps+ lists what is
+    # still pending (municipality_code, certificate).
+    Company = define_data(
+      :id, :tenantId, :legalName, :tradeName, :taxId, :municipalReg,
+      :sendMunicipalReg, :municipalityCode, :defaultServiceCode, :taxRegime, :simpleNational, :specialRegime,
+      :addressStreet, :addressNumber, :addressComplement, :addressDistrict,
+      :addressCity, :addressState, :addressZip, :fiscalSchemaVersion,
+      :environment, :status, :createdAt, :updatedAt, :deletedAt, :setupGaps
+    )
+  end
+end

data/lib/corvo_nfse/types/credits.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module CorvoNfse
+  module Types
+    # Current credit balance for the tenant.
+    CreditBalance = define_data(
+      :tenantId, :balance, :overageUnits, :overageAmountCents, :hardLimit
+    )
+
+    # A purchasable credit plan.
+    CreditPlan = define_data(
+      :id, :slug, :name, :description, :monthlyCreditAllowance, :dailyLimit,
+      :maxActiveCompanies,
+      :creditUnitPriceCents, :throughputRps, :includesWebhooks,
+      :includesXmlDownload, :includesPdfDownload, :includesApiKeys,
+      :supportTier, :active, :createdAt, :updatedAt
+    )
+
+    # A credit ledger transaction. +amount+ is in credits (not BRL); members
+    # ending in +Cents+ are in centavos.
+    CreditTransaction = define_data(
+      :id, :tenantId, :type, :amount, :description, :source, :amountBrlCents,
+      :unitPriceCentsApplied, :planIdSnapshot, :reservedInvoiceId, :periodId,
+      :isReservation, :relatedTransactionId, :createdAt
+    )
+
+    # A public price catalog entry (+GET /plans+), prices in centavos.
+    PlanQuote = define_data(
+      :slug, :name, :monthlyAllowance, :basePriceCents, :perCreditOverageCents,
+      :monthlyTotalCents, :currency
+    )
+
+    # The plan recommended for a monthly volume (+GET /plans/quote+). The wire
+    # names are snake_case.
+    PlanRecommendation = define_data(
+      :volume, :recommended_plan, :plan_name, :monthly_allowance,
+      :overage_credits, :overage_cost_cents, :base_price_cents,
+      :total_estimated_cents, :currency, :billing_cycle
+    )
+  end
+end

data/lib/corvo_nfse/types/invoice.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module CorvoNfse
+  module Types
+    # An NFS-e invoice through its lifecycle.
+    Invoice = define_data(
+      :id, :companyId, :tenantId, :environment, :documentKeyVersion,
+      :emailSnapshot, :externalId, :idempotencyKey, :status, :customerSnapshot,
+      :serviceSnapshot, :taxSnapshot, :amount, :currency, :competenceDate,
+      :dpsId, :dpsSeries, :dpsNumber, :accessKey, :nfseNumber, :fiscalProvider,
+      :fiscalSchemaVersion, :issuedAt, :authorizedAt, :lastErrorCode,
+      :lastErrorMessage, :lastErrorProvider, :documentsReadyAt, :lastEmailStatus,
+      :lastEmailSentAt, :createdAt, :updatedAt, :documentsStatus, :emailStatus,
+      :stage, :scheduledFor
+    )
+
+    # A status transition recorded for an invoice.
+    InvoiceEvent = define_data(
+      :id, :invoiceId, :fromStatus, :toStatus, :reason, :createdAt
+    )
+
+    # A time-limited signed download URL for a generated document.
+    InvoiceDownloadUrl = define_data(
+      :downloadUrl, :expiresAt, :fileName, :mimeType
+    )
+
+    # Result of triggering an invoice e-mail send.
+    InvoiceEmailResult = define_data(:emailId, :status)
+  end
+end

data/lib/corvo_nfse/types/webhook.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module CorvoNfse
+  module Types
+    # A registered webhook endpoint.
+    Webhook = define_data(:id, :url, :events, :active, :createdAt, :updatedAt)
+
+    # A webhook as returned once at creation — includes the signing +secret+.
+    WebhookWithSecret = define_data(
+      :id, :url, :events, :active, :createdAt, :updatedAt, :secret
+    )
+
+    # One delivery attempt record for a webhook.
+    WebhookDelivery = define_data(
+      :id, :tenantId, :webhookConfigId, :eventType, :environment, :url, :payload,
+      :statusCode, :responseBody, :errorMessage, :status, :durationMs,
+      :retryCount, :nextRetryAt, :lastError, :createdAt
+    )
+
+    # Aggregated delivery counters over a recent window.
+    WebhookDeliveryStats = define_data(
+      :total, :sent, :failed, :pending, :delayed
+    )
+  end
+end

data/lib/corvo_nfse/types.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module CorvoNfse
+  # Immutable wire-faithful data types.
+  #
+  # Every type is a +Data+ class whose members mirror the API wire format
+  # exactly (camelCase where the wire is camelCase, snake_case where the wire
+  # is snake_case — e.g. the billing payloads). The SDK never re-cases server
+  # fields: +from_wire+ maps the parsed JSON onto the type by key, and +to_wire+
+  # maps it back verbatim.
+  module Types
+    # Class-side helpers mixed into every type.
+    module ModelMethods
+      # Build an instance from a parsed wire hash (string keys). Missing keys
+      # default to +nil+; unknown extra keys are ignored so the type tolerates
+      # server-side additions.
+      def from_wire(hash)
+        return nil if hash.nil?
+
+        src = hash.is_a?(Hash) ? hash.transform_keys(&:to_sym) : {}
+        vals = members.to_h { |m| [m, src[m]] }
+        new(**vals)
+      end
+    end
+
+    # Instance-side helpers mixed into every type.
+    module InstanceMethods
+      # Back to a wire-format hash (string keys), pass-through of values.
+      def to_wire
+        to_h.transform_keys(&:to_s)
+      end
+    end
+
+    # Define an immutable wire type with the shared from_wire/to_wire helpers.
+    def self.define_data(*members, &blk)
+      Data.define(*members) do
+        extend ModelMethods
+        include InstanceMethods
+        class_eval(&blk) if blk
+      end
+    end
+  end
+end
+
+require_relative "types/common"
+require_relative "types/company"
+require_relative "types/invoice"
+require_relative "types/certificate"
+require_relative "types/webhook"
+require_relative "types/credits"
+require_relative "types/billing"

data/lib/corvo_nfse/util.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module CorvoNfse
+  # Small shared helpers.
+  module Util
+    module_function
+
+    # Percent-encode a single path segment (encodeURIComponent-equivalent).
+    def enc(value)
+      URI.encode_www_form_component(value.to_s).gsub("+", "%20")
+    end
+
+    # True for loopback / RFC1918 / link-local hosts (http:// allowed there).
+    def private_host?(hostname)
+      host = hostname.to_s.downcase.sub(/\.\z/, "")
+      return true if ["localhost", "[::1]", "::1"].include?(host) || host.end_with?(".localhost")
+
+      parts = host.split(".")
+      return false unless parts.length == 4
+      return false unless parts.all? { |p| p.match?(/\A\d+\z/) && p.to_i <= 255 }
+
+      a = parts[0].to_i
+      b = parts[1].to_i
+      a == 127 || a == 10 || a == 0 ||
+        (a == 192 && b == 168) ||
+        (a == 172 && (16..31).cover?(b)) ||
+        (a == 169 && b == 254)
+    end
+  end
+end

data/lib/corvo_nfse/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module CorvoNfse
+  VERSION = "0.1.1"
+end

data/lib/corvo_nfse/webhooks.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module CorvoNfse
+  # Helpers for consuming Corvo webhooks.
+  module Webhooks
+    SIGNATURE_PATTERN = /\Asha256=([0-9a-f]{64})\z/
+
+    # The events a webhook can subscribe to. +webhook.test+ is only sent by
+    # +client.webhooks.test+ and cannot be subscribed.
+    EVENTS = %w[
+      nfse.invoice.authorized
+      nfse.invoice.rejected
+      nfse.invoice.failed
+      nfse.invoice.reconciliation_required
+      nfse.invoice.manual_review
+      nfse.invoice.documents_ready
+      nfse.invoice.email_sent
+      nfse.invoice.email_failed
+      nfse.invoice.fiscal_discrepancy
+    ].freeze
+
+    module_function
+
+    # Verify an ``X-Corvo-Signature: sha256=<hex>`` header (HMAC-SHA256).
+    #
+    # Pass the raw request bytes — re-serialized JSON will not match the HMAC.
+    # Comparison is constant-time via +OpenSSL.fixed_length_secure_compare+.
+    #
+    #   raw = request.body.read
+    #   CorvoNfse::Webhooks.verify_signature(raw, headers["X-Corvo-Signature"], secret)
+    def verify_signature(raw_body, signature_header, secret)
+      return false unless signature_header.is_a?(String) && secret.is_a?(String) && !secret.empty?
+
+      match = SIGNATURE_PATTERN.match(signature_header.strip)
+      return false unless match
+
+      body = raw_body.is_a?(String) ? raw_body : raw_body.to_s
+      expected = OpenSSL::HMAC.hexdigest("SHA256", secret, body)
+      constant_time_equals(match[1], expected)
+    end
+
+    def constant_time_equals(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      OpenSSL.fixed_length_secure_compare(a, b)
+    end
+  end
+end

data/lib/corvo_nfse.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Ruby SDK for the Corvo NFS-e API (https://corvo.tech).
+#
+# A small, stdlib-only client (net/http, uri, json, openssl, base64) exposing
+# the full Corvo NFS-e surface with result-style ``[data, error]`` returns.
+module CorvoNfse
+end
+
+require_relative "corvo_nfse/version"
+require_relative "corvo_nfse/error"
+require_relative "corvo_nfse/util"
+require_relative "corvo_nfse/types"
+require_relative "corvo_nfse/transport"
+require_relative "corvo_nfse/webhooks"
+
+require_relative "corvo_nfse/resources/base"
+require_relative "corvo_nfse/resources/companies"
+require_relative "corvo_nfse/resources/certificates"
+require_relative "corvo_nfse/resources/invoices"
+require_relative "corvo_nfse/resources/webhooks"
+require_relative "corvo_nfse/resources/credits"
+require_relative "corvo_nfse/resources/plans"
+require_relative "corvo_nfse/resources/billing"
+require_relative "corvo_nfse/resources/health"
+
+require_relative "corvo_nfse/client"