vision_api 1.0.0

data/lib/vision_api/multipart.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+
+module VisionAPI
+  # multipart/form-data encoding, written out rather than pulled in.
+  #
+  # The gem depends on nothing but the standard library, and this is the only piece
+  # net/http does not already give us.
+  module Multipart
+    CONTENT_TYPES = {
+      ".pdf" => "application/pdf",
+      ".png" => "image/png",
+      ".jpg" => "image/jpeg",
+      ".jpeg" => "image/jpeg",
+      ".webp" => "image/webp",
+      ".tif" => "image/tiff",
+      ".tiff" => "image/tiff"
+    }.freeze
+
+    module_function
+
+    # Turns whatever the caller passed into <tt>[filename, bytes, content_type]</tt>.
+    #
+    # Accepts a path, a Pathname, an open binary IO, raw bytes, or an explicit
+    # <tt>[filename, bytes]</tt> pair. The filename is cosmetic — the server detects the
+    # type from magic bytes and ignores what we declare — but a sensible one makes
+    # multipart logs readable.
+    def resolve(file)
+      case file
+      when Array
+        name, data = file
+        [name.to_s, data.to_s, content_type_for(name.to_s)]
+      when ->(f) { f.respond_to?(:read) }
+        name = file.respond_to?(:path) ? File.basename(file.path.to_s) : "upload"
+        [name, file.read, content_type_for(name)]
+      when String, ->(f) { f.respond_to?(:to_path) }
+        path = file.respond_to?(:to_path) ? file.to_path : file
+        if path.match?(%r{\Ahttps?://}i)
+          raise UsageError, "Pass a URL as file_url:, not as file:. " \
+                            "file: is a path on disk, an open IO, or the bytes themselves."
+        end
+        return [File.basename(path), File.binread(path), content_type_for(path)] if File.file?(path)
+
+        # Not a path on disk, so treat it as the bytes themselves — which is what a caller
+        # who read the file already has in hand.
+        ["upload", file, "application/octet-stream"]
+      else
+        raise UsageError, "file: must be a path, an open IO, bytes, or [filename, bytes]."
+      end
+    rescue Errno::ENOENT, Errno::EACCES => e
+      raise UsageError, "Could not read file: #{e.message}"
+    end
+
+    # Encodes a multipart body. Returns <tt>[body, content_type]</tt>.
+    #
+    # An array value becomes repeated parts, which is how +questions+ is meant to arrive
+    # over multipart; a hash is JSON-encoded, which is how +schema+ arrives.
+    def encode(fields, file)
+      boundary = "----visionapi#{SecureRandom.hex(16)}"
+      body = +""
+
+      fields.each do |name, value|
+        next if value.nil?
+
+        Array(wrap(value)).each do |item|
+          body << "--#{boundary}\r\n"
+          body << "Content-Disposition: form-data; name=\"#{name}\"\r\n\r\n"
+          body << item
+          body << "\r\n"
+        end
+      end
+
+      if file
+        filename, data, content_type = file
+        body = body.b
+        body << "--#{boundary}\r\n"
+        body << "Content-Disposition: form-data; name=\"file\"; filename=\"#{filename}\"\r\n"
+        body << "Content-Type: #{content_type}\r\n\r\n"
+        body << data.b
+        body << "\r\n"
+      end
+
+      body << "--#{boundary}--\r\n"
+      [body, "multipart/form-data; boundary=#{boundary}"]
+    end
+
+    # @api private
+    def wrap(value)
+      case value
+      when Array then value.map { |item| item.is_a?(String) ? item : JSON.generate(item) }
+      when Hash then JSON.generate(value)
+      # Booleans go out as "true"/"false", not as JSON. Same body as the else branch, kept
+      # separate because it is the one case a reader is likely to expect JSON encoding for.
+      when true, false then value.to_s
+      else value.to_s # rubocop:disable Lint/DuplicateBranch
+      end
+    end
+
+    # @api private
+    def content_type_for(name)
+      CONTENT_TYPES.fetch(File.extname(name.to_s).downcase, "application/octet-stream")
+    end
+  end
+end

data/lib/vision_api/result.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module VisionAPI
+  # Helpers for reading a result.
+  #
+  # None of this is required — <tt>res["result"]["total"]["value"]</tt> is a perfectly good
+  # way to read a field, and responses stay plain hashes. These exist because three rules
+  # trip people up often enough to be worth a method:
+  #
+  # 1. every scalar is wrapped in <tt>{"value", "confidence"}</tt>;
+  # 2. a preset response contains every field of the preset, absent ones as +nil+;
+  # 3. a line-item array is a *bare* array whose cells are wrapped individually — the array
+  #    itself has no confidence, each cell has its own.
+  module Result
+    ORDER = { "low" => 0, "mid" => 1, "high" => 2 }.freeze
+
+    module_function
+
+    # @return [Boolean] whether the node is a wrapped scalar rather than rows or a block
+    def field?(node)
+      node.is_a?(Hash) && node.key?("value") && node.key?("confidence")
+    end
+
+    # @return [Boolean] whether the node is a line-item / repeated-block array
+    def rows?(node)
+      node.is_a?(Array)
+    end
+
+    # Drops the wrappers, recursively.
+    #
+    #   unwrap("total" => {"value" => 12, "confidence" => "high"})  # => {"total" => 12}
+    #
+    # Absent fields stay as +nil+, because "the preset has this field and the document did
+    # not carry it" is information. Pass <tt>drop_null: true</tt> for only what was found.
+    #
+    # @param result [Hash, nil]
+    # @return [Hash]
+    def unwrap(result, drop_null: false)
+      (result || {}).each_with_object({}) do |(key, node), out|
+        if rows?(node)
+          unwrapped = node.map { |row| unwrap(row, drop_null: drop_null) }
+          out[key] = unwrapped unless drop_null && unwrapped.empty?
+        elsif field?(node)
+          next if drop_null && node["value"].nil?
+
+          out[key] = node["value"]
+        elsif node.is_a?(Hash)
+          out[key] = unwrap(node, drop_null: drop_null)
+        end
+      end
+    end
+
+    # @return [Hash, nil] the wrapped scalar, or nil when the result has no such field
+    def field(result, name)
+      node = (result || {})[name.to_s]
+      field?(node) ? node : nil
+    end
+
+    # A scalar field's value directly.
+    #
+    # Returns +default+ when the field is absent from the schema *or* present with a null
+    # value — collapsing the two on purpose, for the common case where you only want the
+    # number.
+    def value(result, name, default = nil)
+      node = field(result, name)
+      node.nil? || node["value"].nil? ? default : node["value"]
+    end
+
+    # @return [Array<Hash>] a line-item array; +[]+ when absent or the document had no lines
+    def rows(result, name)
+      node = (result || {})[name.to_s]
+      rows?(node) ? node : []
+    end
+
+    # @return [Array<String>] the fields the document actually carried
+    def present(result)
+      (result || {}).filter_map do |key, node|
+        if rows?(node)
+          key unless node.empty?
+        elsif field?(node)
+          key unless node["value"].nil?
+        else
+          key
+        end
+      end
+    end
+
+    # @return [Array<String>] the fields that came back empty
+    def missing(result)
+      found = present(result)
+      (result || {}).keys.reject { |key| found.include?(key) }
+    end
+
+    # @return [Boolean] whether the field's confidence is at least +level+
+    def at_least?(node, level)
+      return false unless field?(node)
+
+      ORDER.fetch(node["confidence"], 0) >= ORDER.fetch(level.to_s)
+    end
+
+    # The scalar fields found but below +level+ — your review queue.
+    #
+    # Extract at the default <tt>min_confidence: "low"</tt> so nothing is silently dropped,
+    # then route what came back weak to a human instead of trusting it.
+    def below_confidence(result, level)
+      (result || {}).filter_map do |key, node|
+        key if field?(node) && !node["value"].nil? && !at_least?(node, level)
+      end
+    end
+  end
+end

data/lib/vision_api/version.rb

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

data/lib/vision_api/webhook.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module VisionAPI
+  # Webhook signature verification.
+  #
+  # The delivery carries <tt>X-Vision-Signature: t=<unix seconds>,v1=<hex hmac></tt>, where
+  # the HMAC is <tt>HMAC-SHA256(secret, "{t}.{raw body}")</tt>. Two details are
+  # load-bearing:
+  #
+  # 1. The HMAC covers the *exact bytes received*. Verify before parsing, and never
+  #    re-serialize the JSON first — a re-encode changes key order and whitespace, and the
+  #    signature stops matching for reasons that look like a bug in this library.
+  # 2. After a secret rotation the header carries *several* +v1=+ parts, one per valid
+  #    secret, for a 24-hour grace period. Accept the delivery if any of them matches.
+  module Webhook
+    DEFAULT_TOLERANCE = 300
+
+    module_function
+
+    # Verifies a delivery and returns its parsed payload.
+    #
+    #   # Rails: config.middleware handles the raw body for you via request.raw_post
+    #   def vision_hook
+    #     event = VisionAPI::Webhook.verify(
+    #       request.raw_post, request.headers["X-Vision-Signature"], ENV["VISION_WEBHOOK_SECRET"]
+    #     )
+    #     VisionResultJob.perform_later(event)
+    #     head :accepted                       # any 2xx is success — ack fast, work after
+    #   rescue VisionAPI::WebhookSignatureError
+    #     head :bad_request                    # never parse an unverified body
+    #   end
+    #
+    # @param payload [String] the bytes exactly as received, untouched
+    # @param signature [String, nil] the +X-Vision-Signature+ header
+    # @param secret [String] your signing secret, from https://app.visionapi.io/dashboard/webhooks
+    # @param tolerance [Integer] how far the timestamp may be from now, in seconds. This is
+    #   what stops a captured delivery being replayed later. Pass 0 to skip the check.
+    # @raise [WebhookSignatureError] the delivery cannot be trusted
+    # @return [Hash] the parsed event
+    def verify(payload, signature, secret, tolerance: DEFAULT_TOLERANCE, now: nil)
+      raise WebhookSignatureError, "No signing secret provided." if secret.nil? || secret.empty?
+      raise WebhookSignatureError, "Missing X-Vision-Signature header." if signature.nil? || signature.empty?
+
+      timestamp = nil
+      candidates = []
+      signature.split(",").each do |part|
+        key, _, value = part.strip.partition("=")
+        case key
+        when "t" then timestamp = value
+        when "v1" then candidates << value unless value.empty?
+        end
+      end
+
+      if timestamp.nil? || timestamp.empty? || candidates.empty?
+        raise WebhookSignatureError, "Malformed X-Vision-Signature header."
+      end
+
+      sent_at = Integer(timestamp, exception: false)
+      raise WebhookSignatureError, "Malformed timestamp in X-Vision-Signature." if sent_at.nil?
+
+      if tolerance.positive?
+        drift = ((now || Time.now).to_i - sent_at).abs
+        if drift > tolerance
+          raise WebhookSignatureError,
+                "Delivery timestamp is #{drift}s away from now, outside the #{tolerance}s tolerance."
+        end
+      end
+
+      body = payload.to_s.b
+      expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.".b + body)
+
+      # Rotation sends one v1= per valid secret. secure_compare keeps each comparison
+      # constant-time; checking them all rather than stopping at the first match is the point.
+      matched = candidates.map { |candidate| secure_compare(expected, candidate) }.any?
+      raise WebhookSignatureError, "Signature does not match the request body." unless matched
+
+      begin
+        JSON.parse(body)
+      rescue JSON::ParserError
+        raise WebhookSignatureError, "Delivery body is not valid JSON."
+      end
+    end
+
+    # @api private
+    def secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      OpenSSL.secure_compare(a, b)
+    end
+  end
+end

data/lib/vision_api.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "vision_api/version"
+require_relative "vision_api/errors"
+require_relative "vision_api/multipart"
+require_relative "vision_api/result"
+require_relative "vision_api/webhook"
+require_relative "vision_api/client"
+
+# Official Ruby client for the Vision API — credit-based OCR and visual intelligence.
+#
+# Send an image or a PDF, describe the fields you want in plain language, and get
+# structured JSON back with a confidence level on every value.
+#
+#   require "vision_api"
+#
+#   vision = VisionAPI.new                        # reads ENV["VISION_API_KEY"]
+#   res = vision.analyze(file: "invoice.pdf", preset: "invoice")
+#   res["result"]["invoice_id"]["value"]          # => "A-10422"
+#
+# - Website: https://visionapi.io
+# - Documentation: https://docs.visionapi.io
+# - API keys: https://app.visionapi.io/dashboard/keys
+module VisionAPI
+  # Builds a {Client}. Everything {Client#initialize} accepts is accepted here.
+  #
+  # @return [Client]
+  def self.new(**options)
+    Client.new(**options)
+  end
+end

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: vision_api
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Vision API
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+description: |
+  Send an image or a PDF, describe the fields you want in plain language, and get
+  structured JSON back with a confidence level on every value. Presets for invoices,
+  receipts, IDs and 25 more; custom schemas; visual Q&A; async tasks and signed webhooks.
+email:
+- support@visionapi.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/vision_api.rb
+- lib/vision_api/client.rb
+- lib/vision_api/errors.rb
+- lib/vision_api/multipart.rb
+- lib/vision_api/result.rb
+- lib/vision_api/version.rb
+- lib/vision_api/webhook.rb
+homepage: https://visionapi.io
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://visionapi.io
+  documentation_uri: https://docs.visionapi.io
+  source_code_uri: https://github.com/devrobotlabs/visionapi-ruby
+  bug_tracker_uri: https://github.com/devrobotlabs/visionapi-ruby/issues
+  changelog_uri: https://github.com/devrobotlabs/visionapi-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Official Ruby client for the Vision API — OCR and visual intelligence.
+test_files: []