fiscalrail 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d2a0b93b946f75e4d2733bafaea87dee185f6b7abf5db7c60b7d73864472d63f
+  data.tar.gz: 40ec395e28ee22197bdeb479517022bdf4894c3b89b721fd80a9db8c693309cf
+SHA512:
+  metadata.gz: c4b48066bb84842295979af02f44e7e002fadf22c88bb73252684f748bb71ac82ec3867673bc8c3227a2b18ac7e1b22df98f0ded6c180bf824550e6bb745f5ff
+  data.tar.gz: 8fff2a61e27c474e4ae2c43fb688d3c5aac67212dda270ac332b6c112a256fb0844a248117801798700804c1236437cbaeeb0229fce437f2c13b95cb1b9fbf38

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.4.0 — 2026-09-07
+
+- Start at 0.4.0 to match the Python SDK release with full resource coverage.
+- Initial Ruby SDK covering all 42 operations in the current FiscalRail OpenAPI contract.
+- Handwritten resources with generated response models and operation metadata.
+- Precise decimals, date/time decoding, deeply frozen responses and unknown-field preservation.
+- Explicit client configuration, persistent HTTP connections, safe retries and invoice idempotency.
+- Lazy pagination, PDF metadata/downloads, webhook verification and Spanish tax conveniences.
+- Standalone tests, optional Rails integration verification and gem CI.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FiscalRail
+
+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,231 @@
+# FiscalRail Ruby SDK
+
+A Ruby client for issuing immutable invoices through FiscalRail. Ruby 3.3 or later; no Rails dependency.
+
+Install with Bundler:
+
+```ruby
+gem "fiscalrail", "~> 0.4.0"
+```
+
+## Issue an invoice
+
+```ruby
+require "fiscalrail"
+
+client = FiscalRail::Client.new(api_key: ENV.fetch("FISCALRAIL_API_KEY"))
+
+invoice = client.invoices.issue(
+  customer: "cus_...",
+  lines: [
+    {
+      description: "Consulting services",
+      unit_price: BigDecimal("2500.00"),
+      taxes: [
+        FiscalRail::TaxRegimes::ES::VAT.general,
+        FiscalRail::TaxRegimes::ES::IRPF.professionals
+      ]
+    }
+  ]
+)
+
+client.invoice_pdfs
+  .render_content(invoice.id, locale: "en")
+  .write_to_file("#{invoice.code}.pdf")
+
+client.close
+```
+
+The API key is explicit: the SDK never reads process configuration. The key selects the Test or Live account; there is no separate environment switch.
+
+Requests use ordinary keyword arguments and nested hashes. Both symbol and string keys work in nested hashes. Use `BigDecimal` or strings for precise monetary inputs. `Date` and `Time` are serialized as ISO 8601 strings. Omitted body fields stay omitted; explicit `nil`, `false` and empty arrays are preserved. Business validation stays on the API.
+
+## Responses
+
+Responses are generated, read-only objects under `FiscalRail::Models`:
+
+```ruby
+invoice.id                  # String
+invoice.issue_date          # Date
+invoice.created_at          # Time
+invoice.totals.payable      # BigDecimal
+invoice.request_id          # Request-Id header
+invoice.idempotency_key      # Key used to issue this invoice
+invoice.idempotent_replayed  # Original request ID, or nil
+invoice.to_h                # Nested hashes with string keys and Ruby values
+```
+
+Unknown response fields are retained in `extra_fields`, accessible through `response["field"]` and, when the name does not collide with an existing method, `response.field`. Nested arrays, hashes and values are frozen. `to_h` creates fresh containers. Unknown enum strings are accepted for forward compatibility. Invalid required fields or structural types raise `FiscalRail::ResponseParseError` with the field path and request ID.
+
+## Idempotency and retries
+
+Invoice `issue` and `amend` calls generate an idempotency key when none is supplied. Every retry within that call uses the same key and serialized body. For durable jobs, create and persist a key with the job before its first attempt:
+
+```ruby
+invoice = client.invoices.issue(
+  idempotency_key: saved_job_key,
+  lines: [{ description: "Consulting", unit_price: "100.00",
+            taxes: [FiscalRail::TaxRegimes::ES::VAT.general] }]
+)
+
+amendment = client.invoices.amend(
+  invoice.id,
+  reason: "issued_by_mistake",
+  idempotency_key: saved_amendment_key
+)
+```
+
+A new SDK call without a supplied key generates a new key. It does not deduplicate retries made by your job framework. Never reuse a key for a different operation or payload.
+
+By default, the SDK makes at most two retries for connection failures, timeouts, HTTP 408/429 and 5xx responses, only for operations designated safe: reads, idempotency-protected issuance/amendments, PDF rendering, and destination enable/disable. Ordinary create/update/delete calls are not automatically retried. The SDK honors numeric and HTTP-date `Retry-After` values, bounded to 30 seconds; otherwise it uses exponential backoff. Set `max_retries: 0` to disable retries. Redirects are not followed. Response decoding failures are not retried.
+
+## Resources
+
+| Resource | Methods |
+| --- | --- |
+| `accounts` | `list`, `retrieve`, `update` |
+| `balances` | `retrieve(account_id)` |
+| `account_tax_regimes` | `retrieve(account_id)` |
+| `api_keys` | `list`, `create`, `retrieve`, `delete` |
+| `customers` | `list`, `create`, `retrieve`, `update`, `delete` |
+| `event_destinations` | `list`, `create`, `retrieve`, `update`, `delete`, `enable`, `disable` |
+| `events` | `list`, `retrieve` |
+| `invoice_series` | `list`, `create`, `retrieve`, `update`, `delete` |
+| `invoices` | `list`, `issue`, `retrieve`, `amend` |
+| `invoice_pdfs` | `retrieve`, `render`, `retrieve_content`, `render_content` |
+| `payment_instructions` | `list`, `create`, `retrieve`, `update`, `delete` |
+| `tax_ids` | `retrieve` |
+| `tax_regimes` | `list`, `retrieve` |
+
+`invoice_pdfs.retrieve` and `render` return metadata. Their `_content` variants return `FiscalRail::BinaryContent`, with `content`, `content_type`, `request_id` and `write_to_file(path)`. PDF content is buffered in memory. `locale:` on rendering becomes `Accept-Language`.
+
+## Pagination
+
+`list` retrieves one page, exposing `data`, `has_more`, `request_id` and Enumerable methods over that page. Paginated resources also expose `auto_paging_each`, which fetches subsequent pages lazily:
+
+```ruby
+page = client.customers.list(country: "ES", limit: 25)
+page.each { |customer| puts customer.name }
+
+client.invoices.auto_paging_each(customer: "cus_...", page_size: 100) do |invoice|
+  puts invoice.code
+end
+
+first_ten = client.customers.auto_paging_each.lazy.take(10).to_a
+```
+
+Automatic iteration proceeds forward and preserves filters. Use `list(starting_after: ...)` or `list(ending_before: ...)` to manage cursors yourself. Accounts and tax regimes return single lists and do not expose automatic pagination.
+
+## Payment instructions
+
+```ruby
+instruction = client.payment_instructions.create(
+  label: "Main EUR account",
+  type: "bank_transfer",
+  bank_transfer: {
+    beneficiary: "Example supplier",
+    iban: "ES9121000418450200051332",
+    bic: "CAIXESBBXXX"
+  }
+)
+
+client.accounts.update("acct_...", default_payment_instructions: [instruction.id])
+
+invoice = client.invoices.issue(
+  payment_terms: { due_date: Date.new(2026, 9, 30) },
+  lines: [{ description: "Consulting", unit_price: "100.00",
+            taxes: [FiscalRail::TaxRegimes::ES::VAT.general] }]
+)
+```
+
+Use `payment_terms: { options: [instruction.id] }` to override account defaults, or `options: []` to omit payment instructions.
+
+## Webhooks
+
+Verify the exact raw body before parsing or processing it. For example, in a Rails controller:
+
+```ruby
+event = FiscalRail::Webhooks.construct_event(
+  request.raw_post,
+  request.headers["FiscalRail-Signature"],
+  signing_secret
+)
+```
+
+The verifier uses constant-time HMAC comparison and a five-minute timestamp tolerance in both directions. It accepts multiple `v1` signatures, returns a hash with string keys, and raises `FiscalRail::WebhookSignatureError` on failure. `verify_signature` verifies without parsing and returns the timestamp. Tests can inject `now:`; `tolerance: nil` explicitly disables the age check.
+
+## Errors
+
+```ruby
+begin
+  client.invoices.issue(idempotency_key: saved_job_key, **params)
+rescue FiscalRail::InvalidInvoiceError => error
+  warn error.message
+  error.details.each { |detail| warn "#{detail['field']}: #{detail['message']}" }
+rescue FiscalRail::APIConnectionError => error
+  # Includes APITimeoutError. Retain the key if the outcome is uncertain.
+  warn "Request failed; idempotency key: #{error.idempotency_key}"
+rescue FiscalRail::APIError => error
+  warn "#{error.code}: HTTP #{error.status_code}, request #{error.request_id}"
+end
+```
+
+All SDK errors inherit from `FiscalRail::Error`. API errors retain `code`, `status_code`, `request_id`, `details`, `body` and `idempotency_key`. Known error codes have subclasses; unknown codes remain `APIError`. Parse errors also retain the request ID and idempotency key.
+
+## Connections and configuration
+
+```ruby
+FiscalRail::Client.open(
+  api_key: secret,
+  open_timeout: 5,
+  read_timeout: 30,
+  write_timeout: 30,
+  max_retries: 2
+) do |client|
+  client.accounts.list
+end
+```
+
+`timeout:` sets all three timeout defaults. The default `Net::HTTP` adapter reuses one connection and serializes concurrent requests with a mutex. Use separate clients for concurrent HTTP throughput. A new connection is opened after a process fork. The SDK disables the HTTP library's own retries so requests are not retried twice. `close` releases the connection; the next request can reconnect.
+
+For custom proxy, TLS or observability behavior, inject `adapter:`. It must implement:
+
+```ruby
+def call(method:, uri:, headers:, body:)
+  # Return FiscalRail::NetHTTPAdapter::Response.new(
+  #   status: 200, headers: { "content-type" => "application/json" }, body: "..."
+  # )
+end
+```
+
+`uri` is a `URI` object; `body` is already serialized JSON or nil. Use standard socket/timeout exceptions for transport failures, and disable adapter-level retries. Injected adapters remain caller-owned and are never closed by the SDK. The SDK does not inspect environment variables; the default HTTP library can use its standard proxy environment configuration.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+bundle exec rake generate
+bundle exec rake check_generated
+bundle exec rake build
+```
+
+Generation defaults to the current [published OpenAPI document](https://docs.fiscalrail.com/openapi.yml). To work against a local contract:
+
+```sh
+bundle exec rake generate SCHEMA=../path/to/api.oas.yml
+bundle exec rake check_generated SCHEMA=../path/to/api.oas.yml
+```
+
+The generator emits Ruby response readers and schema/operation metadata under `lib/fiscalrail/generated`. Resource methods, transport, decoding, errors, pagination, webhook verification and tax conveniences are handwritten. Do not edit generated files. There is no RBS support, vendored schema or pinned schema revision. Regular tests are offline; `check_generated` needs the published schema unless a local path is supplied, and intentionally fails when that contract changes.
+
+The fixtures contain public OpenAPI examples plus synthetic webhook, event and amendment payloads. HTTP tests run against a loopback TCP server. An optional test exercises the actual Rails application, test database and PDF renderer:
+
+```sh
+# Run in the FiscalRail Rails checkout with its local dependencies running.
+FISCALRAIL_APP_ROOT="$PWD" bundle exec ruby /absolute/path/to/ruby/test/rails_integration.rb
+```
+
+It creates a Test account inside a test transaction and checks customer creation, null clearing, payment defaults, issuance/replay, pagination, PDF download and amendment. Set `FISCALRAIL_SDK_PDF=/tmp/sdk-invoice.pdf` to retain the rendered PDF for inspection. This test is optional and is not part of the standalone gem CI.
+
+See [RELEASING.md](RELEASING.md) for the release checklist.

data/lib/fiscalrail/binary_content.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module FiscalRail
+  class BinaryContent
+    attr_reader :content, :content_type, :request_id
+
+    def initialize(response)
+      @content = response.body.b.freeze
+      @content_type = response.headers["content-type"]&.freeze
+      @request_id = response.headers["request-id"]&.freeze
+      freeze
+    end
+
+    def write_to_file(path)
+      File.binwrite(path, content)
+    end
+  end
+end

data/lib/fiscalrail/client.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module FiscalRail
+  class Client
+    attr_reader :accounts, :balances, :account_tax_regimes, :api_keys, :customers,
+      :event_destinations, :events, :invoice_series, :invoices, :invoice_pdfs,
+      :payment_instructions, :tax_ids, :tax_regimes
+
+    def initialize(api_key:, base_url: "https://api.fiscalrail.com/v1", timeout: 30,
+      open_timeout: timeout, read_timeout: timeout, write_timeout: timeout, max_retries: 2, adapter: nil)
+      raise ArgumentError, "api_key must be a nonempty string" unless api_key.is_a?(String) && !api_key.empty?
+      raise ArgumentError, "max_retries must be a nonnegative integer" unless max_retries.is_a?(Integer) && max_retries >= 0
+      [open_timeout, read_timeout, write_timeout].each do |value|
+        raise ArgumentError, "timeouts must be positive finite numbers" unless value.is_a?(Numeric) && value.finite? && value.positive?
+      end
+      uri = URI(base_url)
+      raise ArgumentError, "base_url must be an HTTP(S) URL without credentials, query or fragment" unless %w[http https].include?(uri.scheme) && uri.host && !uri.userinfo && !uri.query && !uri.fragment
+
+      @owns_adapter = adapter.nil?
+      @adapter = adapter || NetHTTPAdapter.new(open_timeout: open_timeout, read_timeout: read_timeout, write_timeout: write_timeout)
+      transport = Transport.new(api_key: api_key, base_url: base_url, max_retries: max_retries, adapter: @adapter)
+      @accounts = Resources::Accounts.new(transport)
+      @balances = Resources::Balances.new(transport)
+      @account_tax_regimes = Resources::AccountTaxRegimes.new(transport)
+      @api_keys = Resources::ApiKeys.new(transport)
+      @customers = Resources::Customers.new(transport)
+      @event_destinations = Resources::EventDestinations.new(transport)
+      @events = Resources::Events.new(transport)
+      @invoice_series = Resources::InvoiceSeries.new(transport)
+      @invoices = Resources::Invoices.new(transport)
+      @invoice_pdfs = Resources::InvoicePdfs.new(transport)
+      @payment_instructions = Resources::PaymentInstructions.new(transport)
+      @tax_ids = Resources::TaxIds.new(transport)
+      @tax_regimes = Resources::TaxRegimes.new(transport)
+    end
+
+    def self.open(**options)
+      client = new(**options)
+      return client unless block_given?
+
+      begin
+        yield client
+      ensure
+        client.close
+      end
+    end
+
+    def close
+      @adapter.close if @owns_adapter
+      nil
+    end
+
+    def inspect
+      "#<#{self.class.name}>"
+    end
+  end
+end

data/lib/fiscalrail/decoder.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module FiscalRail
+  class Decoder
+    class Mismatch < StandardError
+      attr_reader :field
+
+      def initialize(message, field)
+        @field = field
+        super(message)
+      end
+    end
+
+    def self.decode(schema, value, metadata: {})
+      new.decode(schema, value, "$", metadata)
+    rescue Mismatch => error
+      name = schema["$ref"]&.split("/")&.last || "API"
+      raise ResponseParseError.new(error.message, model: name, field: error.field,
+        request_id: metadata[:request_id], idempotency_key: metadata[:idempotency_key])
+    end
+
+    def decode(schema, value, path, metadata = {})
+      mismatch("value is not allowed", path) if schema == false
+      return value if schema == true || schema.empty?
+      if schema["$ref"]
+        referenced = Generated::SCHEMAS.fetch(schema.fetch("$ref").split("/").last)
+        return decode(referenced.merge(schema.reject { |key, _| key == "$ref" }), value, path, metadata)
+      end
+
+      if (branches = schema["oneOf"] || schema["anyOf"])
+        if (discriminator = schema["discriminator"]) && value.is_a?(Hash)
+          ref = discriminator.fetch("mapping", {})[value[discriminator.fetch("propertyName")]]
+          return decode({ "$ref" => ref }, value, path, metadata) if ref
+        end
+        failures = []
+        branches.each do |branch|
+          begin
+            return decode(branch, value, path, metadata)
+          rescue Mismatch => error
+            failures << error
+          end
+        end
+        raise failures.max_by { |error| error.field.length }
+      end
+
+      types = Array(schema["type"])
+      return nil if value.nil? && types.include?("null")
+      mismatch("expected #{types.join(' or ')}", path) if value.nil? && !types.empty?
+      mismatch("expected #{schema['const'].inspect}", path) if schema.key?("const") && value != schema["const"]
+
+      case (types - ["null"]).first
+      when "object"
+        mismatch("expected an object", path) unless value.is_a?(Hash)
+        properties = schema.fetch("properties", {})
+        schema.fetch("required", []).each { |key| mismatch("required field is missing", "#{path}.#{key}") unless value.key?(key) }
+        attributes, extra = {}, {}
+        value.each do |key, item|
+          if properties.key?(key)
+            attributes[key] = decode(properties[key], item, "#{path}.#{key}")
+          else
+            additional = schema["additionalProperties"]
+            extra[key] = additional.is_a?(Hash) ? decode(additional, item, "#{path}.#{key}") : item
+          end
+        end
+        return attributes.merge(extra) unless schema["model"]
+
+        Models.const_get(schema.fetch("model"), false).new(attributes, extra_fields: extra, metadata: metadata)
+      when "array"
+        mismatch("expected an array", path) unless value.is_a?(Array)
+        value.each_with_index.map { |item, index| decode(schema.fetch("items", {}), item, "#{path}[#{index}]") }
+      when "string"
+        mismatch("expected a string", path) unless value.is_a?(String)
+        case schema["format"]
+        when "decimal"
+          mismatch("expected a finite decimal string", path) unless value.match?(/\A-?\d+(?:\.\d+)?\z/)
+          BigDecimal(value)
+        when "date" then Date.iso8601(value)
+        when "date-time" then Time.iso8601(value)
+        else value
+        end
+      when "integer"
+        mismatch("expected an integer", path) unless value.is_a?(Integer)
+        value
+      when "number"
+        mismatch("expected a number", path) unless value.is_a?(Numeric)
+        value
+      when "boolean"
+        mismatch("expected a boolean", path) unless value == true || value == false
+        value
+      when "null" then mismatch("expected null", path)
+      else value
+      end
+    rescue ArgumentError => error
+      mismatch(error.message, path)
+    end
+
+    private
+
+    def mismatch(message, path)
+      raise Mismatch.new(message, path)
+    end
+  end
+end

data/lib/fiscalrail/errors.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module FiscalRail
+  class Error < StandardError; end
+  class WebhookSignatureError < Error; end
+
+  class APIConnectionError < Error
+    attr_reader :idempotency_key
+
+    def initialize(message, idempotency_key: nil)
+      @idempotency_key = idempotency_key
+      super(message)
+    end
+  end
+
+  class APITimeoutError < APIConnectionError; end
+
+  class ResponseParseError < Error
+    attr_reader :model, :field, :request_id, :idempotency_key
+
+    def initialize(message, model:, field:, request_id: nil, idempotency_key: nil)
+      @model, @field, @request_id, @idempotency_key = model, field, request_id, idempotency_key
+      super("Could not parse FiscalRail #{model} response at #{field}: #{message}")
+    end
+  end
+
+  class APIError < Error
+    attr_reader :code, :status_code, :request_id, :details, :idempotency_key, :body
+
+    def initialize(message, code:, status_code:, request_id:, details: [], idempotency_key: nil, body: nil)
+      @code, @status_code, @request_id = code, status_code, request_id
+      @details, @idempotency_key, @body = details, idempotency_key, body
+      super(request_id ? "#{message} (request_id: #{request_id})" : message)
+    end
+  end
+
+  class AuthenticationError < APIError; end
+  class InvalidRequestError < APIError; end
+  class ResourceNotFoundError < APIError; end
+  class InvalidCustomerError < APIError; end
+  class CustomerNotFoundError < APIError; end
+  class InvalidInvoiceError < APIError; end
+  class InvalidInvoiceSeriesError < APIError; end
+  class InvalidPaymentInstructionError < APIError; end
+  class InvalidInvoiceAmendmentError < APIError; end
+  class AccountNotConfiguredError < APIError; end
+  class BalanceExhaustedError < APIError; end
+  class IdempotencyConflictError < APIError; end
+  class PdfRenderInProgressError < APIError; end
+  class PdfRenderingUnavailableError < APIError; end
+
+  module Errors
+    CLASSES = {
+      "authentication_required" => AuthenticationError,
+      "invalid_request" => InvalidRequestError,
+      "invalid_idempotency_key" => InvalidRequestError,
+      "resource_not_found" => ResourceNotFoundError,
+      "invalid_customer" => InvalidCustomerError,
+      "customer_not_found" => CustomerNotFoundError,
+      "invalid_invoice" => InvalidInvoiceError,
+      "invalid_invoice_series" => InvalidInvoiceSeriesError,
+      "invalid_payment_instruction" => InvalidPaymentInstructionError,
+      "invalid_invoice_amendment" => InvalidInvoiceAmendmentError,
+      "account_not_configured" => AccountNotConfiguredError,
+      "balance_exhausted" => BalanceExhaustedError,
+      "idempotency_key_in_use" => IdempotencyConflictError,
+      "idempotency_key_mismatch" => IdempotencyConflictError,
+      "pdf_render_in_progress" => PdfRenderInProgressError,
+      "pdf_rendering_unavailable" => PdfRenderingUnavailableError
+    }.freeze
+
+    def self.from_response(status:, headers:, body:, idempotency_key: nil)
+      payload = JSON.parse(body)
+      build(status, headers, payload, idempotency_key)
+    rescue JSON::ParserError
+      build(status, headers, body, idempotency_key)
+    end
+
+    def self.build(status, headers, payload, idempotency_key)
+      error = payload.is_a?(Hash) && payload["error"].is_a?(Hash) ? payload["error"] : {}
+      code = error["code"] || "http_#{status}"
+      details = Array(error["details"]).select { |detail| detail.is_a?(Hash) }
+      CLASSES.fetch(code, APIError).new(
+        error["message"] || "FiscalRail returned HTTP #{status}",
+        code: code, status_code: status, request_id: headers["request-id"],
+        details: details, idempotency_key: idempotency_key, body: payload
+      )
+    end
+  end
+end