invoist 1.0.0

data/lib/invoist/download.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Invoist
+  # A downloaded file: an original document or bill, exactly as it was added.
+  #
+  # @!attribute [r] data
+  #   @return [String] the bytes (binary encoding)
+  # @!attribute [r] content_type
+  #   @return [String] e.g. `application/pdf`
+  # @!attribute [r] filename
+  #   @return [String, nil] the name from `Content-Disposition`, when sent
+  Download = Data.define(:data, :content_type, :filename) do
+    # @return [Integer] the size in bytes
+    def size
+      data.bytesize
+    end
+
+    # Writes the bytes to a file.
+    #
+    # @param path [String, #to_path]
+    # @return [Integer] bytes written
+    def save(path)
+      File.binwrite(path, data)
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class.name} content_type=#{content_type.inspect} filename=#{filename.inspect} size=#{size}>"
+    end
+
+    # @api private
+    # @param header [String, nil] a Content-Disposition value
+    # @return [String, nil]
+    def self.filename_from(header)
+      return nil if header.nil?
+
+      if (encoded = header[/filename\*\s*=\s*(?:UTF-8|utf-8)''([^;]+)/, 1])
+        return URI.decode_www_form_component(encoded.strip.gsub("+", "%2B")).force_encoding(Encoding::UTF_8)
+      end
+
+      header[/filename\s*=\s*"((?:[^"\\]|\\.)*)"/, 1]&.gsub(/\\(.)/, '\1') || header[/filename\s*=\s*([^;\s]+)/, 1]
+    end
+  end
+end

data/lib/invoist/error.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Invoist
+  # Every failure the client raises. Branch on {#code}, a stable identifier;
+  # {#message} is for people and its wording can change.
+  #
+  #   begin
+  #     client.bills.mark_paid(id)
+  #   rescue Invoist::Error => e
+  #     raise unless e.permission_error?
+  #     warn "this key may only read bills (#{e.code})"
+  #   end
+  class Error < StandardError
+    # @return [Integer] the HTTP status, or 0 when no response arrived
+    attr_reader :status
+    # @return [String] a stable machine code, e.g. `invalid_api_key`,
+    #   `not_found`, `network_error`, `timeout`, `unexpected_response`
+    attr_reader :code
+    # @return [String, nil] the `X-Request-Id` response header; quote it to support
+    attr_reader :request_id
+    # @return [String, nil] the raw response body, when there was one
+    attr_reader :body
+    # @return [Integer, nil] seconds from the `Retry-After` header, when sent
+    attr_reader :retry_after
+
+    # @param message [String] human text
+    # @param status [Integer] HTTP status, 0 without a response
+    # @param code [String] stable machine code
+    # @param request_id [String, nil]
+    # @param body [String, nil]
+    # @param retry_after [Integer, nil]
+    def initialize(message, status:, code:, request_id: nil, body: nil, retry_after: nil)
+      super(message)
+      @status = status
+      @code = code
+      @request_id = request_id
+      @body = body
+      @retry_after = retry_after
+    end
+
+    # Builds the error for a non-2xx response from the API's
+    # `{"error":{"code","message"}}` envelope. The code is
+    # `unexpected_response` when the body is something else (a proxy's HTML
+    # page, an empty body) or the envelope has no code; the message is
+    # `Request failed with status <n>` when the API sent none.
+    #
+    # @param status [Integer]
+    # @param body [String, nil] the raw body
+    # @param headers [Hash{String => String}] response headers, lowercase names
+    # @return [Error]
+    def self.from_response(status:, body:, headers: {})
+      raw = body.nil? || body.empty? ? nil : body
+      code, message = envelope(raw)
+      new(message || "Request failed with status #{status}",
+          status: status,
+          code: code || "unexpected_response",
+          request_id: present(headers["x-request-id"]),
+          body: raw,
+          retry_after: integer_seconds(headers["retry-after"]))
+    end
+
+    # @api private
+    # @return [Integer, nil] a non-negative integer number of seconds
+    def self.integer_seconds(value)
+      value = value.to_s.strip
+      value.match?(/\A\d+\z/) ? value.to_i : nil
+    end
+
+    # @api private
+    def self.envelope(raw)
+      return nil if raw.nil?
+
+      detail = JSON.parse(raw.dup.force_encoding(Encoding::UTF_8)).then { |p| p["error"] if p.is_a?(Hash) }
+      return nil unless detail.is_a?(Hash)
+
+      # An envelope missing one key keeps the other.
+      [present(detail["code"]), present(detail["message"])]
+    rescue JSON::ParserError, EncodingError
+      nil
+    end
+    private_class_method :envelope
+
+    # @api private
+    def self.present(value)
+      value.is_a?(String) && !value.empty? ? value : nil
+    end
+    private_class_method :present
+
+    # @return [Boolean] the key is missing, malformed or revoked (401)
+    def auth_error?
+      status == 401
+    end
+
+    # @return [Boolean] the key is valid but lacks the scope, or the route
+    #   belongs to the other kind of account (403)
+    def permission_error?
+      status == 403
+    end
+
+    # @return [Boolean] no such resource (404)
+    def not_found?
+      status == 404
+    end
+
+    # @return [Boolean] too many requests (429)
+    def rate_limited?
+      status == 429
+    end
+
+    # Whether sending the same request again could succeed: no response
+    # arrived, 429, or a server error. Never another 4xx.
+    #
+    # @return [Boolean]
+    def retryable?
+      status.zero? || status == 429 || status >= 500
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class.name} status=#{status} code=#{code.inspect} message=#{message.inspect}" \
+        "#{" request_id=#{request_id.inspect}" if request_id}>"
+    end
+  end
+end

data/lib/invoist/http.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
+require "zlib"
+
+module Invoist
+  # The request loop every method goes through: headers, encoding, the error
+  # envelope and retries.
+  #
+  # @api private
+  class HTTP
+    # Failures where no response arrived at all.
+    TIMEOUT_ERRORS = [Timeout::Error].freeze
+    NETWORK_ERRORS = [SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError, Net::ProtocolError,
+                      Net::HTTPBadResponse, Zlib::Error].freeze
+
+    BASE_DELAY = 0.5
+    MAX_DELAY = 8.0
+    JITTER = 0.2
+    # A Retry-After longer than this is not waited for: the call fails at once.
+    MAX_RETRY_AFTER = 60
+
+    attr_reader :base_url, :timeout, :max_retries
+
+    def initialize(api_key:, base_url:, timeout:, max_retries:, transport:, sleeper:)
+      @api_key = api_key
+      @base_url = base_url
+      @timeout = timeout
+      @max_retries = max_retries
+      @transport = transport
+      @sleeper = sleeper
+    end
+
+    # Sends a request and decodes its JSON answer.
+    #
+    # @return [Object, nil] the decoded body, nil for 204 or an empty body
+    def json(verb, path, query: nil, body: nil, headers: {})
+      response = send_request(verb, path, query: query, headers: headers,
+                                          body: body.nil? ? nil : [JSON.generate(body), "application/json"])
+      decode(response)
+    end
+
+    # Sends a multipart upload.
+    def multipart(path, form, headers: {})
+      decode(send_request("POST", path, body: [form.body, form.content_type], headers: headers))
+    end
+
+    # Fetches raw bytes.
+    #
+    # @return [Download]
+    def binary(path)
+      response = send_request("GET", path)
+      Download.new(data: response.body.b,
+                   content_type: response.header("content-type") || "application/octet-stream",
+                   filename: Download.filename_from(response.header("content-disposition")))
+    end
+
+    # Waits, between polls or retries.
+    def sleep(seconds)
+      @sleeper.call(seconds)
+    end
+
+    # The delay before retry number `attempt` (0-based): Retry-After when the
+    # response has it, otherwise 500ms x 2^attempt with ±20% jitter, at most 8s.
+    def retry_delay(attempt, response = nil)
+      seconds = Error.integer_seconds(response&.header("retry-after"))
+      return seconds.to_f if seconds
+
+      backoff = BASE_DELAY * (2**attempt) * (1 + (((rand * 2) - 1) * JITTER))
+      [backoff, MAX_DELAY].min
+    end
+
+    def url(path, query = nil)
+      pairs = (query || {}).reject { |_, v| v.nil? || v == "" }
+      url = "#{@base_url}#{path}"
+      pairs.empty? ? url : "#{url}?#{URI.encode_www_form(pairs.map { |k, v| [k.to_s, v.to_s] })}"
+    end
+
+    private
+
+    def send_request(verb, path, query: nil, body: nil, headers: {})
+      payload, content_type = body
+      request = Transport::Request.new(http_method: verb, url: url(path, query), timeout: @timeout, body: payload,
+                                       headers: request_headers(headers, content_type))
+      attempt = 0
+      loop do
+        response, error, cause = attempt_once(request)
+        return response if error.nil?
+        raise error, cause: cause unless retry?(error, attempt)
+
+        sleep(retry_delay(attempt, response))
+        attempt += 1
+      end
+    end
+
+    def retry?(error, attempt)
+      return false unless error.retryable? && attempt < @max_retries
+
+      error.retry_after.nil? || error.retry_after <= MAX_RETRY_AFTER
+    end
+
+    # @return [Array(Transport::Response, Error, Exception)] the response, the
+    #   error it means (nil on success), and the low-level cause
+    def attempt_once(request)
+      response = normalize(@transport.call(request))
+      return [response, nil, nil] if (200..299).cover?(response.status)
+
+      [response, Error.from_response(status: response.status, body: response.body,
+                                     headers: { "x-request-id" => response.header("x-request-id"),
+                                                "retry-after" => response.header("retry-after") }), nil]
+    rescue *TIMEOUT_ERRORS => e
+      [nil, Error.new("Request timed out after #{@timeout}s (#{e.class})", status: 0, code: "timeout"), e]
+    rescue *NETWORK_ERRORS => e
+      [nil, Error.new("Network error: #{e.message} (#{e.class})", status: 0, code: "network_error"), e]
+    end
+
+    def normalize(response)
+      return response if response.is_a?(Transport::Response)
+
+      Transport::Response.new(status: Integer(response.status), headers: response.headers.to_h,
+                              body: response.body.to_s)
+    end
+
+    def request_headers(extra, content_type)
+      headers = {
+        "Authorization" => "Bearer #{@api_key}",
+        "Accept" => "application/json",
+        "User-Agent" => USER_AGENT
+      }
+      headers["Content-Type"] = content_type if content_type
+      headers.merge(extra)
+    end
+
+    def decode(response)
+      return nil if response.status == 204 || response.body.empty?
+
+      JSON.parse(response.body.dup.force_encoding(Encoding::UTF_8))
+    rescue JSON::ParserError
+      raise Error.new("The API answered #{response.status} with a body that is not JSON",
+                      status: response.status, code: "unexpected_response", body: response.body,
+                      request_id: response.header("x-request-id"))
+    end
+  end
+end

data/lib/invoist/model.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Invoist
+  # Behaviour shared by every response type in {Invoist::Models}.
+  #
+  # Models are immutable `Data` objects built from the API's JSON with
+  # {ClassMethods#from_h}. Fields read like methods (`bill.total_cents`), and
+  # `bill[:total_cents]`, {#to_h} and {#to_json} are there for code that
+  # wants a Hash.
+  module Model
+    # @api private
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Turns a JSON value into the type a field declares.
+    #
+    # @api private
+    # @param value [Object] the decoded JSON
+    # @param type [Class, Array(Class), nil] a model class, `[model class]` for a list, or nil for plain JSON
+    # @return [Object]
+    def self.coerce(value, type)
+      case type
+      when nil then value
+      when Array then value.is_a?(Array) ? value.map { |v| coerce(v, type.first) } : value
+      else value.is_a?(Hash) ? type.from_h(value) : value
+      end
+    end
+
+    # @api private
+    def self.dump(value)
+      case value
+      when Model then value.to_h
+      when Array then value.map { |v| dump(v) }
+      else value
+      end
+    end
+
+    # Class methods of every model.
+    module ClassMethods
+      # Builds the model from decoded JSON. Missing fields are nil, unknown
+      # ones are ignored: the API adds fields over time.
+      #
+      # @param hash [Hash{String, Symbol => Object}, nil]
+      # @return [self, nil] nil when `hash` is nil
+      # @raise [TypeError] when `hash` is not a Hash
+      def from_h(hash)
+        return nil if hash.nil?
+        raise TypeError, "#{name} is built from a Hash, not #{hash.class}" unless hash.is_a?(Hash)
+
+        types = nested_types
+        attrs = members.to_h do |member|
+          key = member.to_s
+          value = hash.key?(key) ? hash[key] : hash[member]
+          [member, Model.coerce(value, types[member])]
+        end
+        new(**attrs)
+      end
+
+      # Fields holding other models.
+      #
+      # @api private
+      # @return [Hash{Symbol => Object}]
+      def nested_types
+        {}
+      end
+    end
+
+    # Reads a field by name, like a Hash.
+    #
+    # @param key [Symbol, String]
+    # @return [Object, nil] nil for a name the model does not have
+    def [](key)
+      name = key.to_sym
+      self.class.members.include?(name) ? public_send(name) : nil
+    end
+
+    # The model as a Hash with Symbol keys, nested models included.
+    #
+    # @return [Hash{Symbol => Object}]
+    def to_h(&)
+      # self.class.members: a field may itself be called `members`.
+      hash = self.class.members.to_h { |member| [member, Model.dump(public_send(member))] }
+      block_given? ? hash.to_h(&) : hash
+    end
+
+    # @return [String] the model as JSON, with the API's field names
+    def to_json(*)
+      to_h.to_json(*)
+    end
+  end
+end