corvo-nfse 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1a33e26dcbf646148caedcdea5d278c58aca67bd3cca85c67926c33e81f19a2a
+  data.tar.gz: 4951671a468a867155484cc8c42e48cf2d39bdd9ac198966be234e75ba144e44
+SHA512:
+  metadata.gz: d9a528b0402af2bce09e14ea51a74836609357a4acbb31764944ca18155eb73291fdbd28ae3d4301f20e82e7ea8cbea2c903de89de701e2037eeeab0fd3d4645
+  data.tar.gz: f531954b335a40ba209d2da5423fb82c0db8e19df01bf96e2a28b5398eca203771fe6e7acd3c855a98e9b538318f1d80333aca299714bfabd9b1fa9e0ffe771f

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Corvo Technology
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,182 @@
+# corvo-nfse
+
+Ruby SDK for the [Corvo](https://corvo.tech) NFS-e API. Register companies, calculate taxes, issue Brazilian service invoices (NFS-e), follow them by webhook and download the PDF and XML, from Ruby 3.2+.
+
+- **Result-style returns.** Every call returns `[data, error]` where exactly one is `nil`. API, network and timeout failures are values, never raised. The error carries the server's stable `code`, the HTTP `status`, the `request_id`, field-level `details` and `retry_after`.
+- **Pagination built in.** Lists return `Types::Paginated`, and `iterate` walks every page.
+- **Safe retries.** Issuing an invoice and sending an email accept an idempotency key.
+- **Webhook signature check** in constant time.
+- **No runtime dependencies**: it uses `net/http`, `uri`, `json` and `openssl` from the standard library. Library only, no CLI.
+
+Full API reference: <https://corvo.tech/en/api-docs>.
+
+## Installation
+
+```bash
+gem install corvo-nfse
+```
+
+Or in your `Gemfile`:
+
+```ruby
+gem "corvo-nfse"
+```
+
+## Quickstart
+
+Start with a `corvo_test_...` key: invoices issued with it have no fiscal value.
+
+```ruby
+require "corvo_nfse"
+
+client = CorvoNfse::Client.new(api_key: "corvo_test_...") # or set CORVO_API_KEY
+
+page, error = client.companies.list(limit: 10)
+
+if error
+  warn "#{error.code}: #{error.message} (HTTP #{error.status}, request #{error.request_id})"
+else
+  page.data.each { |company| puts company.legalName }
+end
+```
+
+`Client.new` is the only call that raises (`ArgumentError`): it fails fast when no API key is configured or the base URL is invalid. `iterate` also raises, see below.
+
+### Register a company
+
+```ruby
+company, error = client.companies.create(
+  legalName: "Empresa Exemplo Ltda",
+  taxId: "11222333000181",
+  taxRegime: "Simples Nacional",   # "MEI" | "Simples Nacional" | "Lucro Presumido" | "Lucro Real"
+  municipalityCode: "3550308",     # IBGE code, 7 digits
+  defaultServiceCode: "010101"     # optional: used when an invoice omits service.code
+)
+```
+
+In `live`, also upload the A1 certificate. The company is ready when `company.status == "ready"` and `company.setupGaps` is empty.
+
+```ruby
+p12 = File.binread("certificado.p12")
+cert, error = client.certificates.upload(company.id, p12, "senha-do-certificado")
+```
+
+### Estimate the taxes before issuing
+
+Nothing is issued, stored or charged.
+
+```ruby
+estimate, error = client.invoices.calculate(
+  companyTaxId: "11222333000181",
+  service: { description: "Consultoria" },
+  amount: 1500,
+  competenceDate: "2026-10-16"
+)
+# estimate["status"] is "ready" or "blocked": a fiscal gap is data, not an error.
+```
+
+### Issue an invoice
+
+Issuing is asynchronous: a successful call means the request was accepted, not that the invoice is authorized. Follow the status with `invoices.get` or webhooks.
+
+```ruby
+invoice, error = client.invoices.create(
+  {
+    companyTaxId: "11222333000181", # or companyId
+    # customer is optional; when sent, taxId (CPF or CNPJ) is required.
+    customer: { taxId: "52998224725", name: "Cliente", email: "cliente@example.com" },
+    service: { description: "Consultoria" }, # code and city default to the company's
+    amount: 150.5,
+    competenceDate: "2026-10-16",
+    options: { email: { send: true } }
+  },
+  idempotency_key: "order-42" # the same key never issues twice
+)
+
+raise error if error # CorvoNfse::CorvoApiError is safe to raise
+puts invoice.id
+```
+
+Use `options: { type: "SCHEDULE" }` with a future `competenceDate` to schedule the issuance. Parameters and response fields use the API's camelCase wire format, unchanged.
+
+### Walk every page
+
+```ruby
+client.invoices.iterate(companyId: "c_1", status: "authorized") do |inv|
+  puts inv.nfseNumber
+end
+
+client.companies.iterate(limit: 100).lazy.map(&:taxId).first(5) # or lazily, as an Enumerator
+```
+
+`iterate` is the one method that raises: a failed page raises `CorvoNfse::CorvoApiError`, since a block or an Enumerator has no slot for a result.
+
+### Download the PDF or XML
+
+The invoice must be `authorized` and have its documents ready.
+
+```ruby
+file, error = client.invoices.pdf("inv_1")
+File.binwrite("nfse.pdf", file.content) unless error # also file.mime_type and file.file_name
+```
+
+### Verify webhook signatures
+
+```ruby
+raw = request.body.read # the raw bytes: do not re-serialize the JSON
+sig = request.env["HTTP_X_CORVO_SIGNATURE"]
+
+if CorvoNfse::Webhooks.verify_signature(raw, sig, secret)
+  # authentic; deduplicate by the event id, the same event can arrive twice
+else
+  # reject with 400
+end
+```
+
+`CorvoNfse::Webhooks::EVENTS` lists the 9 events you can subscribe to. The `webhook.test` event is only sent by `client.webhooks.test`.
+
+## Resources
+
+| Namespace | Methods |
+| --- | --- |
+| `client.companies` | `create`, `get`, `update`, `remove`, `list`, `iterate` |
+| `client.certificates` | `upload`, `list`, `remove` |
+| `client.invoices` | `create`, `calculate`, `get`, `list`, `iterate`, `events`, `pdf`, `xml`, `download_url`, `send_email` |
+| `client.webhooks` | `list`, `create`, `remove`, `test`, plus `deliveries.list/iterate/stats/retry` |
+| `client.credits` | `balance`, `plans`, `history`, `iterate_history` |
+| `client.billing` | `plan`, `usage` |
+| `client.plans` | `list`, `get`, `quote` (public price catalog) |
+| `client.health` | `live`, `ready` |
+
+Changing plans and the billing portal exist only in the dashboard, so they are not in the SDK. Immutable response types live under `CorvoNfse::Types` as `Data` classes whose members mirror the wire format (for example `Types::Invoice#accessKey`).
+
+## Errors
+
+`CorvoNfse::CorvoApiError` carries `status`, `code`, `message`, `details`, `request_id` and `retry_after`. `code` is the API's `ERROR_*` code, falling back to `http_<status>`; transport failures use `status = 0` and a `code` of `network_error`, `timeout` or `invalid_json`. On `429`, `retry_after` holds the seconds to wait.
+
+## Configuration
+
+```ruby
+CorvoNfse::Client.new(
+  api_key: "corvo_test_...",          # falls back to ENV["CORVO_API_KEY"]
+  base_url: "https://api.corvo.tech", # falls back to ENV["CORVO_BASE_URL"], then the default
+  prefix: "v1",
+  timeout: 30,                        # open/read/write timeout, seconds
+  allow_insecure_http: false          # http:// only for loopback and private hosts
+)
+```
+
+Auth is the `X-API-Key` header. Keys are `corvo_test_...` or `corvo_live_...` and belong to one account and environment; the key decides the environment.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec   # the contract spec is pending without env
+```
+
+The contract spec runs only when `CORVO_API_KEY` and `CORVO_BASE_URL` point to a reachable instance.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

data/lib/corvo_nfse/client.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module CorvoNfse
+  # Entry point for the Corvo NFS-e API.
+  #
+  #   client = CorvoNfse::Client.new(api_key: "corvo_live_xxx")  # or CORVO_API_KEY
+  #   companies, error = client.companies.list(limit: 10)
+  class Client
+    DEFAULT_BASE_URL = "https://api.corvo.tech"
+    ENV_API_KEY = "CORVO_API_KEY"
+    ENV_BASE_URL = "CORVO_BASE_URL"
+
+    attr_reader :billing, :certificates, :companies, :credits, :health,
+                :invoices, :plans, :webhooks, :base_url
+
+    def initialize(api_key: nil, base_url: nil, prefix: Transport::DEFAULT_PREFIX,
+                   timeout: Transport::DEFAULT_TIMEOUT, allow_insecure_http: false)
+      key = api_key || ENV[ENV_API_KEY]
+      if key.nil? || key.empty?
+        raise ArgumentError, "Corvo: api_key is required — pass api_key or set CORVO_API_KEY"
+      end
+
+      base = (base_url || ENV[ENV_BASE_URL] || DEFAULT_BASE_URL).to_s.sub(%r{/+\z}, "")
+      uri = parse_base(base)
+
+      if uri.scheme == "http" && !allow_insecure_http && !Util.private_host?(uri.host)
+        raise ArgumentError,
+              "Corvo: http:// is only allowed for loopback/private hosts " \
+              "(got #{uri.host}). Use https:// or pass allow_insecure_http: true."
+      end
+
+      @transport = Transport.new(api_key: key, base_url: base, prefix: prefix, timeout: timeout)
+      @base_url = @transport.base_url
+      @billing = Resources::Billing.new(@transport)
+      @certificates = Resources::Certificates.new(@transport)
+      @companies = Resources::Companies.new(@transport)
+      @credits = Resources::Credits.new(@transport)
+      @health = Resources::Health.new(@transport)
+      @invoices = Resources::Invoices.new(@transport)
+      @plans = Resources::Plans.new(@transport)
+      @webhooks = Resources::Webhooks.new(@transport)
+    end
+
+    private
+
+    def parse_base(base)
+      uri = URI.parse(base)
+      unless uri.is_a?(URI::HTTP) && uri.host
+        raise ArgumentError, "Corvo: invalid base_url: #{base}"
+      end
+
+      uri
+    rescue URI::InvalidURIError
+      raise ArgumentError, "Corvo: invalid base_url: #{base}"
+    end
+  end
+end

data/lib/corvo_nfse/error.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module CorvoNfse
+  # Typed error carrying the server's stable ``code`` and HTTP context.
+  #
+  # It is both the value inside a ``[nil, error]`` result AND a raiseable
+  # exception. API, network, and timeout failures are returned as values, not
+  # raised. The single documented exception is the ``iterate`` helpers, which
+  # raise the error on first-page failure because a block/enumerator has no
+  # return slot for it.
+  #
+  # Network and timeout failures use ``status = 0`` and a ``code`` of
+  # ``"network_error"`` or ``"timeout"``.
+  class CorvoApiError < StandardError
+    attr_reader :status, :code, :details, :request_id, :retry_after
+
+    def initialize(status:, code:, message:, details: nil, request_id: nil, retry_after: nil)
+      super(message)
+      @status = status
+      @code = code
+      @details = details || []
+      @request_id = request_id
+      @retry_after = retry_after
+    end
+
+    def to_h
+      {
+        status: status,
+        code: code,
+        message: message,
+        details: details,
+        request_id: request_id,
+        retry_after: retry_after
+      }
+    end
+  end
+end

data/lib/corvo_nfse/resources/base.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module CorvoNfse
+  module Resources
+    # Shared constructor for every resource namespace.
+    class Base
+      def initialize(transport)
+        @t = transport
+      end
+    end
+  end
+end

data/lib/corvo_nfse/resources/billing.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module CorvoNfse
+  module Resources
+    # Billing — plan, usage.
+    class Billing < Base
+      def plan
+        @t.request("GET", "/billing/plan", type: Types::BillingPlanResponse)
+      end
+
+      def usage
+        @t.request("GET", "/billing/usage", type: Types::QuotaStatus)
+      end
+    end
+  end
+end

data/lib/corvo_nfse/resources/certificates.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module CorvoNfse
+  module Resources
+    # Certificates — upload (multipart), list, remove.
+    class Certificates < Base
+      # Upload a PKCS#12 certificate (max 50 KiB). The SDK builds the form.
+      def upload(company_id, file, password, file_name: "certificate.p12")
+        fields = [
+          ["file", file, "application/x-pkcs12", file_name],
+          ["password", password]
+        ]
+        @t.request_form(
+          "POST",
+          "/companies/#{Util.enc(company_id)}/certificates",
+          fields,
+          type: Types::Certificate
+        )
+      end
+
+      def list(company_id, limit: nil, cursor: nil)
+        @t.list_page(
+          "/companies/#{Util.enc(company_id)}/certificates",
+          { limit: limit, cursor: cursor },
+          mapper: ->(item) { Types::Certificate.from_wire(item) }
+        )
+      end
+
+      def remove(company_id, certificate_id)
+        @t.request(
+          "DELETE",
+          "/companies/#{Util.enc(company_id)}/certificates/#{Util.enc(certificate_id)}"
+        )
+      end
+    end
+  end
+end

data/lib/corvo_nfse/resources/companies.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module CorvoNfse
+  module Resources
+    # Companies — create, get, update, remove, list, iterate.
+    class Companies < Base
+      def create(**params)
+        @t.request("POST", "/companies", json: params, type: Types::Company)
+      end
+
+      def list(limit: nil, cursor: nil)
+        @t.list_page(
+          "/companies",
+          { limit: limit, cursor: cursor },
+          mapper: ->(item) { Types::Company.from_wire(item) }
+        )
+      end
+
+      def iterate(limit: nil, cursor: nil, &block)
+        @t.iterate(
+          "/companies",
+          { limit: limit, cursor: cursor },
+          mapper: ->(item) { Types::Company.from_wire(item) },
+          &block
+        )
+      end
+
+      def get(id)
+        @t.request("GET", "/companies/#{Util.enc(id)}", type: Types::Company)
+      end
+
+      def update(id, **params)
+        @t.request("PATCH", "/companies/#{Util.enc(id)}", json: params, type: Types::Company)
+      end
+
+      def remove(id)
+        @t.request("DELETE", "/companies/#{Util.enc(id)}")
+      end
+    end
+  end
+end

data/lib/corvo_nfse/resources/credits.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module CorvoNfse
+  module Resources
+    # Credits — balance, plans, history, iterate_history.
+    class Credits < Base
+      PLAN_MAPPER = ->(item) { Types::CreditPlan.from_wire(item) }
+      TX_MAPPER = ->(item) { Types::CreditTransaction.from_wire(item) }
+
+      def balance
+        @t.request("GET", "/credits", type: Types::CreditBalance)
+      end
+
+      def plans(limit: nil, cursor: nil)
+        @t.list_page("/credits/plans", { limit: limit, cursor: cursor }, mapper: PLAN_MAPPER)
+      end
+
+      def history(limit: nil, cursor: nil)
+        @t.list_page("/credits/history", { limit: limit, cursor: cursor }, mapper: TX_MAPPER)
+      end
+
+      def iterate_history(limit: nil, cursor: nil, &block)
+        @t.iterate("/credits/history", { limit: limit, cursor: cursor }, mapper: TX_MAPPER, &block)
+      end
+    end
+  end
+end

data/lib/corvo_nfse/resources/health.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module CorvoNfse
+  module Resources
+    # Public health checks (no envelope — the raw body is returned).
+    class Health < Base
+      def live
+        @t.request("GET", "/health/live", unwrap: "none")
+      end
+
+      def ready
+        @t.request("GET", "/health/ready", unwrap: "none")
+      end
+    end
+  end
+end

data/lib/corvo_nfse/resources/invoices.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module CorvoNfse
+  module Resources
+    # Invoices: create, calculate, get, list, iterate, events, pdf, xml,
+    # download_url, send_email.
+    class Invoices < Base
+      INVOICE_MAPPER = ->(item) { Types::Invoice.from_wire(item) }
+      EVENT_MAPPER = ->(item) { Types::InvoiceEvent.from_wire(item) }
+
+      def create(params, idempotency_key: nil)
+        @t.request(
+          "POST", "/invoices",
+          json: params,
+          idempotency_key: idempotency_key,
+          type: Types::Invoice
+        )
+      end
+
+      # Estimate the taxes without issuing, storing or charging anything.
+      # Same body as +create+. A fiscal gap is not an error: the result has
+      # +"status" => "blocked"+ with +"blocking"+ and +"pendingFields"+. Money
+      # values are decimal strings. Returns the parsed JSON (a Hash).
+      def calculate(params)
+        @t.request("POST", "/invoices/calculate", json: params)
+      end
+
+      def get(id)
+        @t.request("GET", "/invoices/#{Util.enc(id)}", type: Types::Invoice)
+      end
+
+      def list(companyId: nil, status: nil, from: nil, to: nil, externalId: nil, limit: nil, cursor: nil)
+        query = {
+          companyId: companyId, status: status, from: from, to: to,
+          externalId: externalId, limit: limit, cursor: cursor
+        }
+        @t.list_page("/invoices", query, mapper: INVOICE_MAPPER)
+      end
+
+      def iterate(companyId: nil, status: nil, from: nil, to: nil, externalId: nil, limit: nil, cursor: nil, &block)
+        query = {
+          companyId: companyId, status: status, from: from, to: to,
+          externalId: externalId, limit: limit, cursor: cursor
+        }
+        @t.iterate("/invoices", query, mapper: INVOICE_MAPPER, &block)
+      end
+
+      def events(id, limit: nil, cursor: nil)
+        @t.list_page(
+          "/invoices/#{Util.enc(id)}/events",
+          { limit: limit, cursor: cursor },
+          mapper: EVENT_MAPPER
+        )
+      end
+
+      def pdf(id)
+        @t.request_raw("GET", "/invoices/#{Util.enc(id)}/pdf")
+      end
+
+      def xml(id)
+        @t.request_raw("GET", "/invoices/#{Util.enc(id)}/xml")
+      end
+
+      def download_url(id, format = "pdf")
+        @t.request(
+          "POST", "/invoices/#{Util.enc(id)}/download-url",
+          json: { format: format },
+          type: Types::InvoiceDownloadUrl
+        )
+      end
+
+      def send_email(id, idempotency_key: nil)
+        @t.request(
+          "POST", "/invoices/#{Util.enc(id)}/email",
+          idempotency_key: idempotency_key,
+          type: Types::InvoiceEmailResult
+        )
+      end
+    end
+  end
+end

data/lib/corvo_nfse/resources/plans.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module CorvoNfse
+  module Resources
+    # Plans: the public price catalog (monthly cycle only). Prices in centavos.
+    class Plans < Base
+      MAPPER = ->(item) { Types::PlanQuote.from_wire(item) }
+
+      # One page of plan prices, from the smallest to the largest allowance.
+      def list(limit: nil, cursor: nil)
+        @t.list_page("/plans", { limit: limit, cursor: cursor }, mapper: MAPPER)
+      end
+
+      # The price of one plan: free, developer, growth, scale or volume.
+      def get(slug)
+        @t.request("GET", "/plans/#{Util.enc(slug)}", type: Types::PlanQuote)
+      end
+
+      # The plan recommended for +volume+ invoices per month. The data is nil
+      # (with no error) when the volume is missing or not positive.
+      def quote(volume)
+        @t.request("GET", "/plans/quote", query: { volume: volume }, type: Types::PlanRecommendation)
+      end
+    end
+  end
+end

data/lib/corvo_nfse/resources/webhooks.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module CorvoNfse
+  module Resources
+    # Nested ``/webhooks/deliveries`` sub-resource.
+    class Deliveries < Base
+      DELIVERY_MAPPER = ->(item) { Types::WebhookDelivery.from_wire(item) }
+
+      def list(hours: nil, environment: nil, limit: nil, cursor: nil)
+        query = { hours: hours, environment: environment, limit: limit, cursor: cursor }
+        @t.list_page("/webhooks/deliveries", query, mapper: DELIVERY_MAPPER)
+      end
+
+      def iterate(hours: nil, environment: nil, limit: nil, cursor: nil, &block)
+        query = { hours: hours, environment: environment, limit: limit, cursor: cursor }
+        @t.iterate("/webhooks/deliveries", query, mapper: DELIVERY_MAPPER, &block)
+      end
+
+      def stats(hours: nil, environment: nil)
+        @t.request(
+          "GET", "/webhooks/deliveries/stats",
+          query: { hours: hours, environment: environment },
+          type: Types::WebhookDeliveryStats
+        )
+      end
+
+      def retry(delivery_id)
+        @t.request("POST", "/webhooks/deliveries/#{Util.enc(delivery_id)}/retry")
+      end
+    end
+
+    # Webhooks — list, create, remove, test + nested deliveries.
+    class Webhooks < Base
+      WEBHOOK_MAPPER = ->(item) { Types::Webhook.from_wire(item) }
+
+      attr_reader :deliveries
+
+      def initialize(transport)
+        super
+        @deliveries = Deliveries.new(transport)
+      end
+
+      def list(limit: nil, cursor: nil)
+        @t.list_page("/webhooks", { limit: limit, cursor: cursor }, mapper: WEBHOOK_MAPPER)
+      end
+
+      def iterate(limit: nil, cursor: nil, &block)
+        @t.iterate("/webhooks", { limit: limit, cursor: cursor }, mapper: WEBHOOK_MAPPER, &block)
+      end
+
+      # Create a webhook. The +secret+ is returned once, at creation.
+      def create(params)
+        @t.request("POST", "/webhooks", json: params, type: Types::WebhookWithSecret)
+      end
+
+      def remove(id)
+        @t.request("DELETE", "/webhooks/#{Util.enc(id)}")
+      end
+
+      def test(id)
+        @t.request("POST", "/webhooks/#{Util.enc(id)}/test")
+      end
+    end
+  end
+end