fiscalrail 0.4.0

data/lib/fiscalrail/model.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module FiscalRail
+  class Model
+    attr_reader :extra_fields, :request_id, :idempotent_replayed, :idempotency_key
+
+    def initialize(attributes, extra_fields: {}, metadata: {})
+      @attributes = self.class.deep_freeze(attributes)
+      @extra_fields = self.class.deep_freeze(extra_fields)
+      @request_id = metadata[:request_id]&.dup&.freeze
+      @idempotent_replayed = metadata[:idempotent_replayed]&.dup&.freeze
+      @idempotency_key = metadata[:idempotency_key]&.dup&.freeze
+      freeze
+    end
+
+    def [](key)
+      key = key.to_s
+      @attributes.key?(key) ? @attributes[key] : @extra_fields[key]
+    end
+
+    # Unknown fields remain accessible without defining methods on the class.
+    def method_missing(name, *args, **kwargs)
+      return @extra_fields[name.to_s] if args.empty? && kwargs.empty? && @extra_fields.key?(name.to_s)
+
+      super
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @extra_fields.key?(name.to_s) || super
+    end
+
+    def to_h
+      self.class.unwrap(@extra_fields.merge(@attributes))
+    end
+
+    def inspect
+      "#<#{self.class.name}#{self['id'] ? " id=#{self['id'].inspect}" : ''}>"
+    end
+
+    def self.unwrap(value)
+      case value
+      when Model then value.to_h
+      when Hash then value.transform_values { |item| unwrap(item) }
+      when Array then value.map { |item| unwrap(item) }
+      else value
+      end
+    end
+
+    def self.deep_freeze(value)
+      case value
+      when Hash then value.each { |key, item| deep_freeze(key); deep_freeze(item) }
+      when Array then value.each { |item| deep_freeze(item) }
+      end
+      value.freeze
+    end
+  end
+
+  class Page < Model
+    include Enumerable
+
+    def each(&block)
+      return enum_for(:each) unless block
+
+      self["data"].each(&block)
+    end
+  end
+end

data/lib/fiscalrail/resource.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module FiscalRail
+  class Resource
+    def initialize(transport)
+      @transport = transport
+    end
+
+    private
+
+    def request(operation_id, path: {}, params: {}, body: nil, retry_safe: false, idempotency_key: nil, headers: {}, binary: false)
+      operation = Generated::OPERATIONS.fetch(operation_id)
+      route = operation.fetch("path").gsub(/\{([^}]+)\}/) do
+        value = path.fetch(Regexp.last_match(1).to_sym)
+        raise ArgumentError, "Path identifiers must be nonempty strings" unless value.is_a?(String) && !value.empty?
+
+        URI.encode_www_form_component(value).gsub("+", "%20")
+      end
+      headers = headers.merge("Accept" => "application/pdf") if binary
+      response = @transport.request(method: operation.fetch("method"), path: route, params: params,
+        body: body, retry_safe: retry_safe, idempotency_key: idempotency_key, headers: headers)
+      metadata = { request_id: response.headers["request-id"], idempotent_replayed: response.headers["idempotent-replayed"], idempotency_key: idempotency_key }
+      unless operation.fetch("responses").key?(response.status.to_s)
+        raise ResponseParseError.new("unexpected HTTP #{response.status}", model: operation_id, field: "$", **metadata.slice(:request_id, :idempotency_key))
+      end
+      return BinaryContent.new(response) if binary
+
+      schema = operation.fetch("responses").fetch(response.status.to_s)
+      return nil unless schema
+
+      Decoder.decode(schema, JSON.parse(response.body), metadata: metadata)
+    rescue JSON::ParserError => error
+      raise ResponseParseError.new("invalid JSON", model: operation_id, field: "$", **metadata.slice(:request_id, :idempotency_key)), cause: error
+    end
+
+    def request_key(key)
+      return SecureRandom.uuid if key.nil?
+      raise ArgumentError, "idempotency_key must be a nonempty string of at most 255 bytes" unless key.is_a?(String) && key.bytesize.between?(1, 255)
+
+      key
+    end
+  end
+
+  module AutoPagination
+    # Iteration always proceeds forward; reverse cursors belong to #list.
+    def auto_paging_each(page_size: 100, **filters)
+      return enum_for(__method__, page_size: page_size, **filters) unless block_given?
+      raise ArgumentError, "Use list for explicit pagination cursors" unless (filters.keys & %i[limit starting_after ending_before]).empty?
+
+      cursor = nil
+      loop do
+        page = list(**filters, limit: page_size, starting_after: cursor)
+        page.each { |item| yield item }
+        break unless page.has_more && !page.data.empty?
+
+        next_cursor = page.data.last.id
+        raise ResponseParseError.new("pagination cursor did not advance", model: "Page", field: "$.data", request_id: page.request_id) if next_cursor == cursor
+
+        cursor = next_cursor
+      end
+      nil
+    end
+  end
+end

data/lib/fiscalrail/resources/accounts.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module FiscalRail
+  module Resources
+    class Accounts < Resource
+      def list
+        request("listAccounts", retry_safe: true)
+      end
+
+      def retrieve(account_id)
+        request("retrieveAccount", path: { id: account_id }, retry_safe: true)
+      end
+
+      def update(account_id, **params)
+        request("updateAccount", path: { id: account_id }, body: params)
+      end
+    end
+
+    class Balances < Resource
+      def retrieve(account_id)
+        request("retrieveBalance", path: { account_id: account_id }, retry_safe: true)
+      end
+    end
+
+    class AccountTaxRegimes < Resource
+      def retrieve(account_id)
+        request("retrieveAccountTaxRegime", path: { account_id: account_id }, retry_safe: true)
+      end
+    end
+  end
+end

data/lib/fiscalrail/resources/api_keys.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module FiscalRail
+  module Resources
+    class ApiKeys < Resource
+      include AutoPagination
+
+      def create(**params)
+        request("createApiKey", body: params)
+      end
+
+      def retrieve(api_key_id)
+        request("retrieveApiKey", path: { id: api_key_id }, retry_safe: true)
+      end
+
+      def delete(api_key_id)
+        request("deleteApiKey", path: { id: api_key_id })
+      end
+
+      def list(limit: nil, starting_after: nil, ending_before: nil)
+        request("listApiKeys", params: { limit: limit, starting_after: starting_after, ending_before: ending_before }, retry_safe: true)
+      end
+    end
+  end
+end

data/lib/fiscalrail/resources/customers.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module FiscalRail
+  module Resources
+    class Customers < Resource
+      include AutoPagination
+
+      def create(**params)
+        request("createCustomer", body: params)
+      end
+
+      def retrieve(customer_id)
+        request("retrieveCustomer", path: { id: customer_id }, retry_safe: true)
+      end
+
+      def update(customer_id, **params)
+        request("updateCustomer", path: { id: customer_id }, body: params)
+      end
+
+      def delete(customer_id)
+        request("deleteCustomer", path: { id: customer_id })
+      end
+
+      def list(q: nil, country: nil, limit: nil, starting_after: nil, ending_before: nil)
+        request("listCustomers", params: { q: q, country: country, limit: limit, starting_after: starting_after, ending_before: ending_before }, retry_safe: true)
+      end
+    end
+  end
+end

data/lib/fiscalrail/resources/event_destinations.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module FiscalRail
+  module Resources
+    class EventDestinations < Resource
+      include AutoPagination
+
+      def create(**params)
+        request("createEventDestination", body: params)
+      end
+
+      def retrieve(destination_id)
+        request("retrieveEventDestination", path: { id: destination_id }, retry_safe: true)
+      end
+
+      def update(destination_id, **params)
+        request("updateEventDestination", path: { id: destination_id }, body: params)
+      end
+
+      def delete(destination_id)
+        request("deleteEventDestination", path: { id: destination_id })
+      end
+
+      def enable(destination_id)
+        request("enableEventDestination", path: { id: destination_id }, retry_safe: true)
+      end
+
+      def disable(destination_id)
+        request("disableEventDestination", path: { id: destination_id }, retry_safe: true)
+      end
+
+      def list(limit: nil, starting_after: nil, ending_before: nil)
+        request("listEventDestinations", params: { limit: limit, starting_after: starting_after, ending_before: ending_before }, retry_safe: true)
+      end
+    end
+  end
+end

data/lib/fiscalrail/resources/events.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module FiscalRail
+  module Resources
+    class Events < Resource
+      include AutoPagination
+
+      def retrieve(event_id)
+        request("retrieveEvent", path: { id: event_id }, retry_safe: true)
+      end
+
+      def list(types: nil, limit: nil, starting_after: nil, ending_before: nil)
+        request("listEvents", params: { types: types&.join(","), limit: limit, starting_after: starting_after, ending_before: ending_before }, retry_safe: true)
+      end
+    end
+  end
+end

data/lib/fiscalrail/resources/invoice_pdfs.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module FiscalRail
+  module Resources
+    class InvoicePdfs < Resource
+      def retrieve(invoice_id)
+        request("retrieveInvoicePdf", path: { invoice_id: invoice_id }, retry_safe: true)
+      end
+
+      def retrieve_content(invoice_id)
+        request("retrieveInvoicePdf", path: { invoice_id: invoice_id }, retry_safe: true, binary: true)
+      end
+
+      def render(invoice_id, locale: nil)
+        request("renderInvoicePdf", path: { invoice_id: invoice_id }, headers: locale ? { "Accept-Language" => locale } : {}, retry_safe: true)
+      end
+
+      def render_content(invoice_id, locale: nil)
+        request("renderInvoicePdf", path: { invoice_id: invoice_id }, headers: locale ? { "Accept-Language" => locale } : {}, retry_safe: true, binary: true)
+      end
+    end
+  end
+end

data/lib/fiscalrail/resources/invoice_series.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module FiscalRail
+  module Resources
+    class InvoiceSeries < Resource
+      include AutoPagination
+
+      def create(**params)
+        request("createInvoiceSeries", body: params)
+      end
+
+      def retrieve(series_id)
+        request("retrieveInvoiceSeries", path: { id: series_id }, retry_safe: true)
+      end
+
+      def update(series_id, **params)
+        request("updateInvoiceSeries", path: { id: series_id }, body: params)
+      end
+
+      def delete(series_id)
+        request("deleteInvoiceSeries", path: { id: series_id })
+      end
+
+      def list(limit: nil, starting_after: nil, ending_before: nil)
+        request("listInvoiceSeries", params: { limit: limit, starting_after: starting_after, ending_before: ending_before }, retry_safe: true)
+      end
+    end
+  end
+end

data/lib/fiscalrail/resources/invoices.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module FiscalRail
+  module Resources
+    class Invoices < Resource
+      include AutoPagination
+
+      def issue(idempotency_key: nil, **params)
+        request("issueInvoice", body: params, retry_safe: true, idempotency_key: request_key(idempotency_key))
+      end
+
+      def retrieve(invoice_id)
+        request("retrieveInvoice", path: { id: invoice_id }, retry_safe: true)
+      end
+
+      def amend(invoice_id, reason:, replacement: nil, idempotency_key: nil)
+        body = { reason: reason }
+        body[:replacement] = replacement unless replacement.nil?
+        request("amendInvoice", path: { invoice_id: invoice_id }, body: body,
+          retry_safe: true, idempotency_key: request_key(idempotency_key))
+      end
+
+      def list(q: nil, customer: nil, issue_date_from: nil, issue_date_to: nil, limit: nil, starting_after: nil, ending_before: nil)
+        request("listInvoices", params: { q: q, customer: customer, issue_date_from: issue_date_from, issue_date_to: issue_date_to,
+          limit: limit, starting_after: starting_after, ending_before: ending_before }, retry_safe: true)
+      end
+    end
+  end
+end

data/lib/fiscalrail/resources/payment_instructions.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module FiscalRail
+  module Resources
+    class PaymentInstructions < Resource
+      include AutoPagination
+
+      def create(**params)
+        request("createPaymentInstruction", body: params)
+      end
+
+      def retrieve(instruction_id)
+        request("retrievePaymentInstruction", path: { id: instruction_id }, retry_safe: true)
+      end
+
+      def update(instruction_id, **params)
+        request("updatePaymentInstruction", path: { id: instruction_id }, body: params)
+      end
+
+      def delete(instruction_id)
+        request("deletePaymentInstruction", path: { id: instruction_id })
+      end
+
+      def list(limit: nil, starting_after: nil, ending_before: nil)
+        request("listPaymentInstructions", params: { limit: limit, starting_after: starting_after, ending_before: ending_before }, retry_safe: true)
+      end
+    end
+  end
+end

data/lib/fiscalrail/resources/tax_regimes.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module FiscalRail
+  module Resources
+    class TaxRegimes < Resource
+      def list
+        request("listTaxRegimes", retry_safe: true)
+      end
+
+      def retrieve(regime_id)
+        request("retrieveTaxRegime", path: { id: regime_id }, retry_safe: true)
+      end
+    end
+
+    class TaxIds < Resource
+      def retrieve(tax_id)
+        request("retrieveTaxId", path: { id: tax_id }, retry_safe: true)
+      end
+    end
+  end
+end

data/lib/fiscalrail/serialization.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "date"
+require "time"
+
+module FiscalRail
+  module Serialization
+    module_function
+
+    def json_value(value)
+      case value
+      when BigDecimal
+        raise ArgumentError, "Decimal must be finite" unless value.finite?
+
+        value.to_s("F")
+      when Time, DateTime then value.iso8601
+      when Date then value.iso8601
+      when Model then json_value(value.to_h)
+      when Hash
+        value.each_with_object({}) do |(key, item), result|
+          raise ArgumentError, "Duplicate JSON key: #{key}" if result.key?(key.to_s)
+
+          result[key.to_s] = json_value(item)
+        end
+      when Array then value.map { |item| json_value(item) }
+      when Symbol then value.to_s
+      when String, Integer, Float, TrueClass, FalseClass, NilClass then value
+      else raise ArgumentError, "Cannot serialize #{value.class} to JSON"
+      end
+    end
+  end
+end

data/lib/fiscalrail/tax_regimes/es.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module FiscalRail
+  module TaxRegimes
+    module ES
+      module VAT
+        def self.general = { tax: "vat", rule: "general" }.freeze
+        def self.reduced = { tax: "vat", rule: "reduced" }.freeze
+        def self.super_reduced = { tax: "vat", rule: "super_reduced" }.freeze
+        def self.exempt_intra_eu_goods = { tax: "vat", rule: "exempt_intra_eu_goods" }.freeze
+        def self.not_subject_place_of_supply = { tax: "vat", rule: "not_subject_place_of_supply" }.freeze
+      end
+
+      module IRPF
+        def self.professionals = { tax: "irpf", rule: "professionals" }.freeze
+        def self.new_professionals = { tax: "irpf", rule: "new_professionals" }.freeze
+      end
+    end
+  end
+end

data/lib/fiscalrail/transport.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+require "thread"
+
+module FiscalRail
+  # The adapter boundary also makes custom proxy/TLS/instrumentation possible.
+  # Adapters return Response and implement #call(method:, uri:, headers:, body:).
+  class NetHTTPAdapter
+    Response = Struct.new(:status, :headers, :body, keyword_init: true)
+
+    def initialize(open_timeout:, read_timeout:, write_timeout:)
+      @open_timeout, @read_timeout, @write_timeout = open_timeout, read_timeout, write_timeout
+      @mutex = Mutex.new
+    end
+
+    def call(method:, uri:, headers:, body:)
+      @mutex.synchronize do
+        origin = [Process.pid, uri.scheme, uri.host, uri.port]
+        if @origin != origin || !@http&.started?
+          disconnect
+          @http = Net::HTTP.new(uri.host, uri.port)
+          @http.use_ssl = uri.scheme == "https"
+          @http.open_timeout = @open_timeout
+          @http.read_timeout = @read_timeout
+          @http.write_timeout = @write_timeout
+          @http.max_retries = 0 # The SDK alone decides which operations are safe.
+          @http.start
+          @origin = origin
+        end
+        request = Net::HTTPGenericRequest.new(method, !body.nil?, method != "HEAD", uri.request_uri, headers)
+        request.body = body if body
+        result = @http.request(request)
+        Response.new(status: result.code.to_i, headers: result.each_header.to_h, body: result.body || "")
+      rescue IOError, SystemCallError, SocketError, Timeout::Error, OpenSSL::SSL::SSLError, Net::HTTPBadResponse, Net::ProtocolError
+        disconnect
+        raise
+      end
+    end
+
+    def close
+      @mutex.synchronize { disconnect }
+    end
+
+    private
+
+    def disconnect
+      @http.finish if @http&.started?
+    rescue IOError, SystemCallError
+      nil
+    ensure
+      @http = nil
+      @origin = nil
+    end
+  end
+
+  class Transport
+    CONNECTION_ERRORS = [IOError, SystemCallError, SocketError, OpenSSL::SSL::SSLError, Net::HTTPBadResponse, Net::ProtocolError].freeze
+
+    def initialize(api_key:, base_url:, max_retries:, adapter:, sleeper: Kernel.method(:sleep))
+      @api_key, @base_url, @max_retries, @adapter, @sleeper = api_key, base_url.sub(%r{/+\z}, ""), max_retries, adapter, sleeper
+    end
+
+    def request(method:, path:, body: nil, params: {}, headers: {}, retry_safe:, idempotency_key: nil)
+      uri = URI("#{@base_url}#{path}")
+      query = Serialization.json_value(params.reject { |_, value| value.nil? })
+      uri.query = URI.encode_www_form(query) unless query.empty?
+      request_headers = {
+        "Authorization" => "Bearer #{@api_key}", "Accept" => "application/json",
+        "User-Agent" => "fiscalrail-ruby/#{VERSION}"
+      }.merge(headers)
+      request_headers["Idempotency-Key"] = idempotency_key if idempotency_key
+      request_headers["Content-Type"] = "application/json" unless body.nil?
+      encoded = body.nil? ? nil : JSON.generate(Serialization.json_value(body))
+      attempt = 0
+      loop do
+        begin
+          response = @adapter.call(method: method, uri: uri, headers: request_headers, body: encoded)
+        rescue Timeout::Error => error
+          if retry_safe && attempt < @max_retries
+            wait(attempt)
+            attempt += 1
+            next
+          end
+          raise APITimeoutError.new("Request to FiscalRail timed out", idempotency_key: idempotency_key), cause: error
+        rescue *CONNECTION_ERRORS => error
+          if retry_safe && attempt < @max_retries
+            wait(attempt)
+            attempt += 1
+            next
+          end
+          raise APIConnectionError.new("Could not connect to FiscalRail", idempotency_key: idempotency_key), cause: error
+        end
+        response.headers = response.headers.transform_keys { |key| key.to_s.downcase }
+        return response if response.status.between?(200, 299)
+
+        if retry_safe && attempt < @max_retries && ([408, 429].include?(response.status) || response.status >= 500)
+          wait(attempt, response.headers["retry-after"])
+          attempt += 1
+          next
+        end
+        raise Errors.from_response(status: response.status, headers: response.headers, body: response.body, idempotency_key: idempotency_key)
+      end
+    end
+
+    private
+
+    def wait(attempt, retry_after = nil)
+      delay = begin
+        Float(retry_after) if retry_after
+      rescue ArgumentError, TypeError
+        begin
+          Time.httpdate(retry_after) - Time.now
+        rescue ArgumentError
+          nil
+        end
+      end
+      delay = 0.25 * (2**attempt) unless delay&.finite?
+      @sleeper.call([[delay, 0].max, 30].min)
+    end
+  end
+end

data/lib/fiscalrail/version.rb

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

data/lib/fiscalrail/webhooks.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "json"
+require_relative "errors"
+
+module FiscalRail
+  module Webhooks
+    DEFAULT_TOLERANCE = 300
+    module_function
+
+    def verify_signature(payload, signature, secret, tolerance: DEFAULT_TOLERANCE, now: Time.now)
+      raise ArgumentError, "tolerance must be nonnegative or nil" unless tolerance.nil? || (tolerance.is_a?(Numeric) && tolerance.finite? && tolerance >= 0)
+      raise WebhookSignatureError, "Missing signing secret" unless secret.is_a?(String) && !secret.empty?
+      raise WebhookSignatureError, "Payload must be a raw string" unless payload.is_a?(String)
+      raise WebhookSignatureError, "Missing FiscalRail-Signature header" unless signature.is_a?(String)
+
+      fields = signature.split(",").map { |item| item.strip.split("=", 2) }
+      timestamps = fields.select { |key, _| key == "t" }.map(&:last)
+      signatures = fields.select { |key, _| key == "v1" }.map(&:last)
+      unless timestamps.length == 1 && timestamps.first&.match?(/\A\d+\z/) && !signatures.empty?
+        raise WebhookSignatureError, "Malformed FiscalRail-Signature header"
+      end
+      timestamp = Integer(timestamps.first, 10)
+      expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.".b + payload.b)
+      valid = signatures.any? do |candidate|
+        candidate && candidate.bytesize == expected.bytesize && OpenSSL.fixed_length_secure_compare(expected, candidate)
+      end
+      raise WebhookSignatureError, "No matching FiscalRail webhook signature" unless valid
+      raise WebhookSignatureError, "FiscalRail webhook timestamp is outside the allowed tolerance" if tolerance && (now.to_f - timestamp).abs > tolerance
+
+      timestamp
+    end
+
+    def construct_event(payload, signature, secret, **options)
+      verify_signature(payload, signature, secret, **options)
+      event = JSON.parse(payload)
+      raise WebhookSignatureError, "FiscalRail webhook payload must be a JSON object" unless event.is_a?(Hash)
+
+      event
+    rescue JSON::ParserError
+      raise WebhookSignatureError, "FiscalRail webhook payload is not valid JSON"
+    end
+  end
+end

data/lib/fiscalrail.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "fiscalrail/version"
+require_relative "fiscalrail/errors"
+require_relative "fiscalrail/model"
+require_relative "fiscalrail/serialization"
+require_relative "fiscalrail/generated/contract"
+require_relative "fiscalrail/generated/models"
+require_relative "fiscalrail/decoder"
+require_relative "fiscalrail/binary_content"
+require_relative "fiscalrail/transport"
+require_relative "fiscalrail/resource"
+require_relative "fiscalrail/resources/accounts"
+require_relative "fiscalrail/resources/api_keys"
+require_relative "fiscalrail/resources/customers"
+require_relative "fiscalrail/resources/event_destinations"
+require_relative "fiscalrail/resources/events"
+require_relative "fiscalrail/resources/invoice_series"
+require_relative "fiscalrail/resources/invoices"
+require_relative "fiscalrail/resources/invoice_pdfs"
+require_relative "fiscalrail/resources/payment_instructions"
+require_relative "fiscalrail/resources/tax_regimes"
+require_relative "fiscalrail/client"
+require_relative "fiscalrail/tax_regimes/es"
+require_relative "fiscalrail/webhooks"