invoist 1.0.0

data/lib/invoist/params.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Invoist
+  # Formats method arguments for the query string.
+  #
+  # @api private
+  module Params
+    module_function
+
+    # @return [String, nil] `"true"` or `"false"`
+    def boolean(name, value)
+      case value
+      when nil then nil
+      when true then "true"
+      when false then "false"
+      else raise ArgumentError, "#{name} must be true or false, not #{value.inspect}"
+      end
+    end
+
+    # @return [String, nil] `YYYY-MM`, from a String, Date or Time (in local time)
+    def month(name, value)
+      return nil if value.nil?
+      return local(value).strftime("%Y-%m") if value.respond_to?(:strftime)
+      return value if value.is_a?(String) && value.match?(/\A\d{4}-\d{2}\z/)
+
+      raise ArgumentError, "#{name} must be a Date or a \"YYYY-MM\" string, not #{value.inspect}"
+    end
+
+    # @return [String, nil] `YYYY-MM-DD`, from a String, Date or Time (in local time)
+    def date(name, value)
+      return nil if value.nil?
+      return local(value).strftime("%Y-%m-%d") if value.respond_to?(:strftime)
+      return value if value.is_a?(String) && value.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+
+      raise ArgumentError, "#{name} must be a Date or a \"YYYY-MM-DD\" string, not #{value.inspect}"
+    end
+
+    # A Time or DateTime moved to the local zone, so it names the calendar
+    # day the caller sees; a Date is already a calendar day.
+    def local(value)
+      value.respond_to?(:hour) && value.respond_to?(:to_time) ? value.to_time.getlocal : value
+    end
+
+    # @return [Integer, nil]
+    def integer(name, value)
+      return nil if value.nil?
+      raise ArgumentError, "#{name} must be an Integer, not #{value.inspect}" unless value.is_a?(Integer)
+
+      value
+    end
+
+    # A path segment, percent-encoded.
+    #
+    # @return [String]
+    def id(value)
+      value = value.to_s
+      raise ArgumentError, "an id is required" if value.empty?
+
+      value.b.gsub(/[^A-Za-z0-9\-._~]/) { |c| format("%%%02X", c.ord) }
+    end
+  end
+end

data/lib/invoist/transport.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+
+module Invoist
+  # The HTTP layer, kept apart so it can be swapped: pass any object with
+  # `call(request) -> response` as `transport:` to {Client#initialize}, for
+  # tests or for an HTTP library of your choice.
+  #
+  # A transport sends one request and returns whatever status came back. It
+  # raises on failures without a response (connection refused, DNS, TLS,
+  # timeouts: `Timeout::Error`, `SystemCallError`, `SocketError`, `IOError`,
+  # `OpenSSL::SSL::SSLError`); the client turns those into {Invoist::Error}
+  # and decides whether to retry.
+  module Transport
+    # One HTTP request.
+    #
+    # @!attribute [r] http_method
+    #   @return [String] `GET`, `POST` or `DELETE`
+    # @!attribute [r] url
+    #   @return [String] the absolute URL, query string included
+    # @!attribute [r] headers
+    #   @return [Hash{String => String}]
+    # @!attribute [r] body
+    #   @return [String, nil] the encoded body (binary for uploads)
+    # @!attribute [r] timeout
+    #   @return [Numeric] seconds allowed to connect, and for each read and write
+    Request = Data.define(:http_method, :url, :headers, :body, :timeout)
+
+    # One HTTP response.
+    #
+    # @!attribute [r] status
+    #   @return [Integer]
+    # @!attribute [r] headers
+    #   @return [Hash{String => String}] header names in any case
+    # @!attribute [r] body
+    #   @return [String] the raw body, empty when there was none
+    Response = Data.define(:status, :headers, :body) do
+      # @param name [String] a header name, in any case
+      # @return [String, nil]
+      def header(name)
+        wanted = name.downcase
+        headers.each { |key, value| return Array(value).join(", ") if key.to_s.downcase == wanted }
+        nil
+      end
+    end
+
+    # The default transport, on the standard library's Net::HTTP. It honours
+    # the usual `http_proxy`/`https_proxy`/`no_proxy` environment variables
+    # and verifies TLS certificates.
+    class NetHTTP
+      # Sends the request on a fresh connection.
+      #
+      # @param request [Request]
+      # @return [Response]
+      def call(request)
+        uri = URI(request.url)
+        req = Net::HTTPGenericRequest.new(request.http_method, !request.body.nil?, true, uri.request_uri,
+                                          request.headers)
+        req.body = request.body unless request.body.nil?
+        res = connection(uri, request.timeout).start { |conn| conn.request(req) }
+        Response.new(status: res.code.to_i, headers: res.each_header.to_h, body: res.body.to_s)
+      end
+
+      private
+
+      def connection(uri, timeout)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = timeout
+        http.read_timeout = timeout
+        http.write_timeout = timeout
+        http.ssl_timeout = timeout
+        http
+      end
+    end
+  end
+end

data/lib/invoist/upload.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Invoist
+  # A file to upload: bytes, the filename Invoist shows, and a content type.
+  #
+  # Methods that take a file accept an Upload or anything {Upload.wrap}
+  # understands: a path (String or Pathname), an open File or other IO, a
+  # Rails/Rack uploaded file, or a Hash `{data:, filename:, content_type:}`.
+  #
+  #   client.extract("invoice.pdf")
+  #   client.extract(File.open("scan.jpg", "rb"))
+  #   client.extract(Invoist::Upload.new(pdf_bytes, filename: "invoice.pdf"))
+  #   client.extract(params[:file]) # in a Rails controller
+  class Upload
+    # Content types guessed from a filename's extension, when none is given.
+    CONTENT_TYPES = {
+      ".pdf" => "application/pdf",
+      ".png" => "image/png",
+      ".jpg" => "image/jpeg",
+      ".jpeg" => "image/jpeg",
+      ".webp" => "image/webp",
+      ".heic" => "image/heic",
+      ".tif" => "image/tiff",
+      ".tiff" => "image/tiff"
+    }.freeze
+
+    # @return [String] the bytes, binary encoded
+    attr_reader :data
+    # @return [String]
+    attr_reader :filename
+    # @return [String]
+    attr_reader :content_type
+
+    # @param data [String] the file's bytes
+    # @param filename [String] the name Invoist records and shows
+    # @param content_type [String, nil] guessed from the filename when nil
+    def initialize(data, filename:, content_type: nil)
+      raise ArgumentError, "filename is required" if filename.nil? || filename.to_s.empty?
+
+      @data = data.to_s.b
+      @filename = filename.to_s
+      @content_type = content_type || self.class.guess_content_type(@filename)
+    end
+
+    # Turns any supported file input into an Upload, reading it into memory
+    # so a retried request can send it again.
+    #
+    # @param input [Upload, String, Pathname, IO, #read, Hash]
+    # @return [Upload]
+    # @raise [ArgumentError] for a path that is not a file
+    # @raise [TypeError] for anything else
+    def self.wrap(input)
+      case input
+      when Upload then input
+      when Hash then from_hash(input)
+      when String then from_path(input)
+      else
+        if defined?(::Pathname) && input.is_a?(::Pathname) then from_path(input)
+        elsif input.respond_to?(:read) then from_io(input)
+        elsif input.respond_to?(:to_path) then from_path(input.to_path)
+        else
+          raise TypeError, "can't upload a #{input.class}: pass a path, an IO, or Invoist::Upload.new(bytes, filename:)"
+        end
+      end
+    end
+
+    # @api private
+    def self.guess_content_type(filename)
+      CONTENT_TYPES.fetch(File.extname(filename).downcase, "application/octet-stream")
+    end
+
+    # @api private
+    def self.from_hash(hash)
+      hash = hash.transform_keys(&:to_sym)
+      data = hash.key?(:data) ? hash[:data] : hash[:io]&.read
+      raise ArgumentError, "an upload Hash needs :data (or :io) and :filename" if data.nil?
+
+      new(data, filename: hash[:filename], content_type: hash[:content_type])
+    end
+    private_class_method :from_hash
+
+    # @api private
+    def self.from_path(path)
+      path = path.to_s
+      raise ArgumentError, "no such file: #{path} (for bytes, use Invoist::Upload.new(data, filename:))" \
+        unless File.file?(path)
+
+      new(File.binread(path), filename: File.basename(path))
+    end
+    private_class_method :from_path
+
+    # @api private
+    def self.from_io(io)
+      io.binmode if io.respond_to?(:binmode)
+      filename = io_filename(io)
+      content_type = io.content_type if io.respond_to?(:content_type)
+      new(io.read, filename: filename, content_type: content_type.is_a?(String) ? content_type : nil)
+    end
+    private_class_method :from_io
+
+    # @api private
+    def self.io_filename(io)
+      name = io.original_filename if io.respond_to?(:original_filename)
+      name ||= File.basename(io.path) if io.respond_to?(:path) && io.path.is_a?(String)
+      name.nil? || name.empty? ? "upload" : name
+    end
+    private_class_method :io_filename
+
+    # @return [String]
+    def inspect
+      "#<#{self.class.name} filename=#{filename.inspect} content_type=#{content_type.inspect} " \
+        "size=#{data.bytesize}>"
+    end
+  end
+
+  # A `multipart/form-data` body, encoded in memory.
+  #
+  # @api private
+  class Multipart
+    attr_reader :body, :content_type
+
+    # @param parts [Array(String, Upload)] field name and file, in order
+    def initialize(parts)
+      boundary = "invoist-#{SecureRandom.hex(16)}"
+      @content_type = "multipart/form-data; boundary=#{boundary}"
+      body = String.new(encoding: Encoding::BINARY)
+      parts.each do |name, upload|
+        body << "--#{boundary}\r\n"
+        body << "Content-Disposition: form-data; name=\"#{escape(name)}\"; " \
+                "filename=\"#{escape(upload.filename)}\"\r\n".b
+        body << "Content-Type: #{upload.content_type}\r\n\r\n"
+        body << upload.data << "\r\n"
+      end
+      body << "--#{boundary}--\r\n"
+      @body = body.freeze
+    end
+
+    private
+
+    # Quotes and line breaks are percent-encoded, as browsers do, so a
+    # filename can't break out of its header.
+    def escape(value)
+      value.to_s.gsub("\"", "%22").gsub("\r", "%0D").gsub("\n", "%0A")
+    end
+  end
+end

data/lib/invoist/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Invoist
+  # The gem's version, shared by every official Invoist SDK.
+  VERSION = "1.0.0"
+end

data/lib/invoist/webhook.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module Invoist
+  # Checks that a webhook really came from Invoist.
+  #
+  # Every delivery carries an `X-Invoist-Signature` header,
+  # `t=<unix seconds>,v1=<hex HMAC-SHA256>`, signed over `"<t>.<raw body>"`
+  # with the endpoint's secret. Verify it before trusting anything in the
+  # body: an endpoint that skips this accepts whatever anyone posts to it.
+  #
+  # Pass the raw request body, byte for byte. Parsing the JSON and
+  # serialising it again changes it, and the signature no longer matches:
+  #
+  #   # Rails
+  #   event = Invoist::Webhook.verify(request.raw_post,
+  #                                   request.headers["X-Invoist-Signature"],
+  #                                   ENV.fetch("INVOIST_WEBHOOK_SECRET"))
+  module Webhook
+    # A document was added.
+    DOCUMENT_CREATED = "document.created"
+    # A document was read.
+    EXTRACTION_COMPLETED = "extraction.completed"
+    # Reading a document failed.
+    EXTRACTION_FAILED = "extraction.failed"
+    # Something was flagged for a person to check.
+    REVIEW_ITEM_CREATED = "review_item.created"
+    # A flagged item was resolved or dismissed.
+    REVIEW_ITEM_RESOLVED = "review_item.resolved"
+    # Someone sent a document that was asked for.
+    DOCUMENT_REQUEST_FULFILLED = "document_request.fulfilled"
+    # Every event type.
+    EVENT_TYPES = [DOCUMENT_CREATED, EXTRACTION_COMPLETED, EXTRACTION_FAILED, REVIEW_ITEM_CREATED,
+                   REVIEW_ITEM_RESOLVED, DOCUMENT_REQUEST_FULFILLED].freeze
+
+    # The header with the signature.
+    SIGNATURE_HEADER = "X-Invoist-Signature"
+    # The header with the event's type.
+    EVENT_HEADER = "X-Invoist-Event"
+    # The header with the delivery's id, the same on every retry of it.
+    DELIVERY_HEADER = "X-Invoist-Delivery"
+    # How old (or how far ahead) a signature may be, in seconds.
+    DEFAULT_TOLERANCE = 300
+
+    # A verified event.
+    #
+    # @!attribute [r] id
+    #   @return [String] the event's id; deduplicate on it
+    # @!attribute [r] type
+    #   @return [String] one of {EVENT_TYPES}, or a newer one
+    # @!attribute [r] created_at
+    #   @return [String] RFC 3339 time
+    # @!attribute [r] data
+    #   @return [Hash{String => Object}] the event's payload, as sent
+    Event = Data.define(:id, :type, :created_at, :data) do
+      include Model
+    end
+
+    module_function
+
+    # Verifies a delivery and returns its event.
+    #
+    # @param payload [String, #read] the raw request body
+    # @param signature_header [String, nil] the `X-Invoist-Signature` value
+    # @param secret [String] the endpoint's signing secret
+    # @param tolerance [Integer] seconds `t` may differ from now, either way;
+    #   0 turns the check off
+    # @param now [Integer, Time, nil] the current time, for tests
+    # @return [Event]
+    # @raise [Error] status 400, code `invalid_signature` (missing or
+    #   malformed header, or no matching signature) or `signature_too_old`
+    #   (outside the tolerance)
+    # @raise [ArgumentError] when the secret is empty
+    def verify(payload, signature_header, secret, tolerance: DEFAULT_TOLERANCE, now: nil)
+      raise ArgumentError, "a webhook secret is required" if secret.nil? || secret.to_s.empty?
+
+      body = raw_bytes(payload)
+      timestamp, signatures = parse_header(signature_header.to_s)
+      if timestamp.nil? || signatures.empty?
+        fail_with("invalid_signature", "The #{SIGNATURE_HEADER} header is missing or malformed")
+      end
+
+      expected = hmac(secret, timestamp, body)
+      matched = signatures.map { |candidate| secure_compare(expected, candidate) }.any?
+      fail_with("invalid_signature", "No signature matches the payload") unless matched
+
+      # The time only after the signature: a forged request is invalid however old it is.
+      if tolerance.positive? && ((now || Time.now).to_i - timestamp.to_i).abs > tolerance
+        fail_with("signature_too_old", "The signature's timestamp is outside the #{tolerance}s tolerance")
+      end
+
+      parse_event(body)
+    end
+
+    # Signs a payload the way Invoist does, to test your own endpoint.
+    #
+    # @param payload [String]
+    # @param secret [String]
+    # @param timestamp [Integer] Unix seconds
+    # @return [String] an `X-Invoist-Signature` header value
+    def sign(payload, secret, timestamp: Time.now.to_i)
+      "t=#{timestamp},v1=#{hmac(secret, timestamp, raw_bytes(payload))}"
+    end
+
+    # @api private
+    def raw_bytes(payload)
+      (payload.respond_to?(:read) ? payload.read : payload.to_s).b
+    end
+
+    # @api private
+    def hmac(secret, timestamp, body)
+      OpenSSL::HMAC.hexdigest("SHA256", secret.to_s.b, "#{timestamp}.".b + body)
+    end
+
+    # @api private
+    # @return [Array(String, Array<String>), Array(nil, Array)] the timestamp and the v1 signatures
+    def parse_header(header)
+      timestamps = []
+      signatures = []
+      header.split(",").each do |part|
+        key, value = part.strip.split("=", 2)
+        next if value.nil? || value.empty?
+
+        timestamps << value if key == "t"
+        signatures << value if key == "v1"
+      end
+      timestamp = timestamps.first if timestamps.size == 1 && timestamps.first.match?(/\A\d+\z/)
+      [timestamp, signatures]
+    end
+
+    # @api private
+    def secure_compare(expected, candidate)
+      expected.bytesize == candidate.bytesize && OpenSSL.fixed_length_secure_compare(expected, candidate)
+    end
+
+    # @api private
+    def parse_event(body)
+      parsed = JSON.parse(body.dup.force_encoding(Encoding::UTF_8))
+      raise JSON::ParserError, "not an event" unless parsed.is_a?(Hash) && parsed["type"].is_a?(String)
+
+      Event.from_h(parsed)
+    rescue JSON::ParserError, EncodingError
+      fail_with("invalid_payload", "The payload is signed but is not a JSON event")
+    end
+
+    # @api private
+    def fail_with(code, message)
+      raise Error.new(message, status: 400, code: code)
+    end
+
+    private_class_method :raw_bytes, :hmac, :parse_header, :secure_compare, :parse_event, :fail_with
+  end
+end

data/lib/invoist.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "invoist/version"
+require_relative "invoist/error"
+require_relative "invoist/model"
+require_relative "invoist/models"
+require_relative "invoist/transport"
+require_relative "invoist/download"
+require_relative "invoist/upload"
+require_relative "invoist/params"
+require_relative "invoist/http"
+require_relative "invoist/bills"
+require_relative "invoist/client"
+require_relative "invoist/webhook"
+
+# The official Ruby client for the Invoist API.
+#
+# Start with {Invoist::Client}; check webhooks with {Invoist::Webhook.verify};
+# every failure is an {Invoist::Error}. See https://invoi.st/docs.
+module Invoist
+  # Sent with every request.
+  USER_AGENT = "invoist-ruby/#{VERSION} (ruby #{RUBY_VERSION})".freeze
+
+  # Shorthand for {Client#initialize}.
+  #
+  # @return [Client]
+  def self.new(...)
+    Client.new(...)
+  end
+end