veryfi 3.0.0 → 4.0.0

data/lib/veryfi/api/w2_split.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Veryfi
+  module Api
+    # W-2 splitting endpoints (`/partner/w2s-set/`).
+    #
+    # Use these when you have a single file containing multiple W-2 forms.
+    # Veryfi will split it and process each W-2 separately; you receive a
+    # collection that references the individual {W2} ids it produced.
+    #
+    # @see https://docs.veryfi.com/api/split-and-process-a-w-2/
+    class W2Split
+      include FilePayload
+
+      ENDPOINT = "/partner/w2s-set/"
+
+      attr_reader :request
+
+      def initialize(request)
+        @request = request
+      end
+
+      # List previously processed W-2 sets.
+      #
+      # @param params [Hash] optional query-string parameters
+      # @return [Veryfi::Resource]
+      def all(params = {})
+        request.get(ENDPOINT, params)
+      end
+
+      # Fetch a single W-2 set by id.
+      #
+      # @param id [Integer]
+      # @param params [Hash] optional query-string parameters
+      # @return [Veryfi::Resource]
+      def get(id, params = {})
+        request.get("#{ENDPOINT}#{id}/", params)
+      end
+
+      # Upload a multi-W-2 file and split-and-process it.
+      #
+      # @param raw_params [Hash]
+      # @option raw_params [String] :file_path **required.** Local path.
+      # @option raw_params [String] :file_name (basename of `:file_path`)
+      # @return [Veryfi::Resource]
+      def process(raw_params)
+        params = raw_params.transform_keys(&:to_sym)
+        file_path = params.delete(:file_path)
+        file_name = params.delete(:file_name)
+
+        payload = file_payload(file_path, file_name).merge(params)
+
+        request.post(ENDPOINT, payload)
+      end
+
+      # URL variant of {#process}.
+      #
+      # @param raw_params [Hash]
+      # @option raw_params [String]        :file_url   single URL
+      # @option raw_params [Array<String>] :file_urls  list of URLs (alternative)
+      # @option raw_params [Integer]       :max_pages_to_process (`nil` = all pages)
+      # @return [Veryfi::Resource]
+      def process_url(raw_params)
+        request.post(ENDPOINT, raw_params.transform_keys(&:to_sym))
+      end
+    end
+  end
+end

data/lib/veryfi/api/w8.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Veryfi
+  module Api
+    # W-8 BEN-E endpoints (`/partner/w-8ben-e/`).
+    #
+    # @see https://docs.veryfi.com/api/w-8ben-e/
+    class W8
+      include FilePayload
+      include TagOperations
+
+      ENDPOINT = "/partner/w-8ben-e/"
+
+      attr_reader :request
+
+      def initialize(request)
+        @request = request
+      end
+
+      # List previously processed W-8 BEN-E documents.
+      #
+      # @param params [Hash] optional query-string parameters
+      # @option params [String]  :created_date__gt   "YYYY-MM-DD HH:MM:SS" — strictly after
+      # @option params [String]  :created_date__gte  after or equal
+      # @option params [String]  :created_date__lt   strictly before
+      # @option params [String]  :created_date__lte  before or equal
+      # @option params [Integer] :page               (1)
+      # @option params [Integer] :page_size          (50)
+      # @return [Veryfi::Resource] `{ "documents" => [...] }`
+      def all(params = {})
+        request.get(ENDPOINT, params)
+      end
+
+      # Fetch a single W-8 by id.
+      #
+      # @param id [Integer]
+      # @param params [Hash] optional query-string parameters
+      # @return [Veryfi::Resource]
+      def get(id, params = {})
+        request.get("#{ENDPOINT}#{id}/", params)
+      end
+
+      # Upload a W-8 file and extract its fields.
+      #
+      # @param raw_params [Hash]
+      # @option raw_params [String] :file_path **required.** Local path.
+      # @option raw_params [String] :file_name (basename of `:file_path`)
+      # @return [Veryfi::Resource]
+      def process(raw_params)
+        params = raw_params.transform_keys(&:to_sym)
+        file_path = params.delete(:file_path)
+        file_name = params.delete(:file_name)
+
+        payload = file_payload(file_path, file_name).merge(params)
+
+        request.post(ENDPOINT, payload)
+      end
+
+      # URL variant of {#process}.
+      #
+      # @param raw_params [Hash]
+      # @option raw_params [String] :file_url  **required.**
+      # @option raw_params [String] :file_name (basename of `:file_url`)
+      # @return [Veryfi::Resource]
+      def process_url(raw_params)
+        params = raw_params.transform_keys(&:to_sym)
+        params[:file_name] ||= File.basename(params[:file_url]) if params[:file_url]
+
+        request.post(ENDPOINT, params)
+      end
+
+      # Update writable fields on a processed W-8.
+      #
+      # @param id [Integer]
+      # @param params [Hash]
+      # @return [Veryfi::Resource]
+      def update(id, params)
+        request.put("#{ENDPOINT}#{id}/", params)
+      end
+
+      # Delete a W-8.
+      #
+      # @param id [Integer]
+      # @return [Veryfi::Resource]
+      def delete(id)
+        request.delete("#{ENDPOINT}#{id}/")
+      end
+    end
+  end
+end

data/lib/veryfi/api/w9.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Veryfi
+  module Api
+    # W-9 endpoints (`/partner/w9s/`).
+    #
+    # @see https://docs.veryfi.com/api/w9s/
+    class W9
+      include FilePayload
+      include TagOperations
+
+      ENDPOINT = "/partner/w9s/"
+
+      attr_reader :request
+
+      def initialize(request)
+        @request = request
+      end
+
+      # List previously processed W-9 documents.
+      #
+      # @param params [Hash] optional query-string parameters
+      # @option params [String]  :created_date__gt   "YYYY-MM-DD HH:MM:SS" — strictly after
+      # @option params [String]  :created_date__gte  after or equal
+      # @option params [String]  :created_date__lt   strictly before
+      # @option params [String]  :created_date__lte  before or equal
+      # @option params [Integer] :page               (1)
+      # @option params [Integer] :page_size          (50)
+      # @return [Veryfi::Resource] `{ "documents" => [...] }`
+      def all(params = {})
+        request.get(ENDPOINT, params)
+      end
+
+      # Fetch a single W-9 by id.
+      #
+      # @param id [Integer]
+      # @param params [Hash] optional query-string parameters
+      # @option params [Boolean] :bounding_boxes     (`false`) Include bounding-box info.
+      # @option params [Boolean] :confidence_details (`false`) Include per-field confidence scores.
+      # @return [Veryfi::Resource]
+      def get(id, params = {})
+        request.get("#{ENDPOINT}#{id}/", params)
+      end
+
+      # Upload a W-9 file and extract its fields.
+      #
+      # @param raw_params [Hash]
+      # @option raw_params [String] :file_path **required.** Local path.
+      # @option raw_params [String] :file_name (basename of `:file_path`)
+      # @return [Veryfi::Resource]
+      def process(raw_params)
+        params = raw_params.transform_keys(&:to_sym)
+        file_path = params.delete(:file_path)
+        file_name = params.delete(:file_name)
+
+        payload = file_payload(file_path, file_name).merge(params)
+
+        request.post(ENDPOINT, payload)
+      end
+
+      # URL variant of {#process}.
+      #
+      # @param raw_params [Hash]
+      # @option raw_params [String] :file_url  **required.**
+      # @option raw_params [String] :file_name (basename of `:file_url`)
+      # @return [Veryfi::Resource]
+      def process_url(raw_params)
+        params = raw_params.transform_keys(&:to_sym)
+        params[:file_name] ||= File.basename(params[:file_url]) if params[:file_url]
+
+        request.post(ENDPOINT, params)
+      end
+
+      # Update writable fields on a processed W-9.
+      #
+      # @param id [Integer]
+      # @param params [Hash]
+      # @return [Veryfi::Resource]
+      def update(id, params)
+        request.put("#{ENDPOINT}#{id}/", params)
+      end
+
+      # Delete a W-9.
+      #
+      # @param id [Integer]
+      # @return [Veryfi::Resource]
+      def delete(id)
+        request.delete("#{ENDPOINT}#{id}/")
+      end
+    end
+  end
+end

data/lib/veryfi/client.rb

@@ -1,7 +1,46 @@
 # frozen_string_literal: true
 
 module Veryfi
+  # The user-facing entry point.
+  #
+  # @example Basic usage
+  #   client = Veryfi::Client.new(
+  #     client_id:     ENV["VERYFI_CLIENT_ID"],
+  #     client_secret: ENV["VERYFI_CLIENT_SECRET"],
+  #     username:      ENV["VERYFI_USERNAME"],
+  #     api_key:       ENV["VERYFI_API_KEY"]
+  #   )
+  #   client.document.process(file_path: "./receipt.jpg")
+  #
+  # @example Custom Faraday configuration (persistent connections + retries)
+  #   client = Veryfi::Client.new(
+  #     client_id:     "…",
+  #     client_secret: "…",
+  #     username:      "…",
+  #     api_key:       "…",
+  #     faraday: ->(conn) {
+  #       conn.request  :retry, max: 3, interval: 0.5, backoff_factor: 2,
+  #                             retry_statuses: [429, 502, 503, 504]
+  #       conn.response :logger, Rails.logger if defined?(Rails)
+  #       conn.adapter  :net_http_persistent
+  #     }
+  #   )
   class Client
+    # DSL: declare an API namespace as a lazily-memoized reader.
+    #
+    # @example
+    #   api_namespace :document, Veryfi::Api::Document
+    #
+    # @param name [Symbol]
+    # @param klass [Class] API class accepting a `Veryfi::Request` in its constructor
+    # @return [void]
+    def self.api_namespace(name, klass)
+      ivar = :"@_#{name}"
+      define_method(name) do
+        instance_variable_get(ivar) || instance_variable_set(ivar, klass.new(request))
+      end
+    end
+
     attr_reader :request
 
     def initialize(
@@ -11,26 +50,31 @@ module Veryfi
       api_key:,
       base_url: "https://api.veryfi.com/api/",
       api_version: "v8",
-      timeout: 20
+      timeout: 20,
+      faraday: nil
     )
-      @request = Veryfi::Request.new(client_id, client_secret, username, api_key, base_url, api_version, timeout)
+      @request = Veryfi::Request.new(
+        client_id, client_secret, username, api_key,
+        base_url, api_version, timeout, faraday
+      )
     end
 
-    def document
-      @_document ||= Veryfi::Api::Document.new(request)
-    end
-
-    def line_item
-      @_line_item ||= Veryfi::Api::LineItem.new(request)
-    end
-
-    def tag
-      @_tag ||= Veryfi::Api::Tag.new(request)
-    end
-
-    def document_tag
-      @_document_tag ||= Veryfi::Api::DocumentTag.new(request)
-    end
+    api_namespace :document,             Veryfi::Api::Document
+    api_namespace :line_item,            Veryfi::Api::LineItem
+    api_namespace :tax_line,             Veryfi::Api::TaxLine
+    api_namespace :tag,                  Veryfi::Api::Tag
+    api_namespace :document_tag,         Veryfi::Api::DocumentTag
+    api_namespace :any_document,         Veryfi::Api::AnyDocument
+    api_namespace :bank_statement,       Veryfi::Api::BankStatement
+    api_namespace :bank_statement_split, Veryfi::Api::BankStatementSplit
+    api_namespace :business_card,        Veryfi::Api::BusinessCard
+    api_namespace :check,                Veryfi::Api::Check
+    api_namespace :classify,             Veryfi::Api::Classify
+    api_namespace :pdf_split,            Veryfi::Api::PdfSplit
+    api_namespace :w2,                   Veryfi::Api::W2
+    api_namespace :w2_split,             Veryfi::Api::W2Split
+    api_namespace :w8,                   Veryfi::Api::W8
+    api_namespace :w9,                   Veryfi::Api::W9
 
     def api_url
       request.api_url

data/lib/veryfi/configuration.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Veryfi
+  # Process-wide settings used by {Veryfi.client} to build the shared
+  # singleton client. Mirrors the keyword arguments of
+  # {Veryfi::Client#initialize}; defaults match the client's defaults.
+  class Configuration
+    ATTRS = %i[
+      client_id client_secret username api_key
+      base_url api_version timeout faraday
+    ].freeze
+
+    attr_accessor(*ATTRS)
+
+    def initialize
+      @base_url    = "https://api.veryfi.com/api/"
+      @api_version = "v8"
+      @timeout     = 20
+    end
+
+    # @return [Hash] the configuration as a keyword-arg-ready Hash. Keys
+    #   with `nil` values are still included; {Veryfi.client} calls
+    #   `.compact` before passing it to {Veryfi::Client#initialize}.
+    def to_h
+      ATTRS.to_h { |attr| [attr, public_send(attr)] }
+    end
+  end
+end

data/lib/veryfi/error.rb

@@ -3,30 +3,116 @@
 require "json"
 
 module Veryfi
+  # Namespace + factory for every error raised by this SDK.
+  #
+  # All errors inherit from {VeryfiError}, so callers that only need to
+  # know "something went wrong with Veryfi" can keep using:
+  #
+  #   begin
+  #     client.document.process(file_path: path)
+  #   rescue Veryfi::Error::VeryfiError => e
+  #     # …
+  #   end
+  #
+  # Callers that want to react differently per HTTP status can rescue a
+  # more specific subclass:
+  #
+  #   begin
+  #     client.document.process(file_path: path)
+  #   rescue Veryfi::Error::Unauthorized       then refresh_credentials!
+  #   rescue Veryfi::Error::TooManyRequests    then back_off
+  #   rescue Veryfi::Error::ServerError        then schedule_retry
+  #   rescue Veryfi::Error::VeryfiError        then log_and_raise
+  #   end
   class Error
-    def self.from_response(status, response)
-      if response.empty?
-        VeryfiError.new(format("%<code>d", code: status))
-      else
-        VeryfiError.new(format("%<code>d, %<message>s", code: status, message: response["error"]), response)
-      end
-    end
-
+    # Base class for every Veryfi SDK error.
+    #
+    # `#message` returns the pretty-printed JSON error payload when one is
+    # available, otherwise the formatted `"<status>"` / `"<status>, <error>"`
+    # string. The `#status` and `#response` accessors give callers
+    # programmatic access to the same information.
     class VeryfiError < StandardError
-      attr_reader :message
+      attr_reader :message, :status, :response
 
-      def initialize(message = "An error occurred", response = {})
-        @message = if response.empty?
+      def initialize(message = "An error occurred", response = {}, status = nil)
+        @status = status
+        @response = response
+        @message = if response.nil? || response.empty?
           message
         else
           JSON.pretty_generate(response)
         end
-        super(message)
+        super(@message)
       end
 
       def to_s
         message
       end
     end
+
+    # 400 — request was malformed or failed server-side validation.
+    class BadRequest < VeryfiError; end
+    # 401 — credentials are missing, invalid, or expired.
+    class Unauthorized < VeryfiError; end
+    # 403 — credentials are valid but lack permission for this resource.
+    class AccessLimitReached < VeryfiError; end
+    # 404 — the resource id does not exist (or has been deleted).
+    class NotFound < VeryfiError; end
+    # 408 — the request timed out before Veryfi could respond.
+    class RequestTimeout < VeryfiError; end
+    # 409 — request conflicts with current resource state.
+    class Conflict < VeryfiError; end
+    # 415 — uploaded file type is not supported by the endpoint.
+    class UnsupportedMediaType < VeryfiError; end
+    # 429 — you've hit a rate limit. Back off and retry.
+    class TooManyRequests < VeryfiError; end
+    # Catch-all for any other 4xx the server returns.
+    class ClientError < VeryfiError; end
+    # 5xx — Veryfi reported an internal error. Retrying with backoff is usually safe.
+    class ServerError < VeryfiError; end
+
+    STATUS_MAP = {
+      400 => BadRequest,
+      401 => Unauthorized,
+      403 => AccessLimitReached,
+      404 => NotFound,
+      408 => RequestTimeout,
+      409 => Conflict,
+      415 => UnsupportedMediaType,
+      429 => TooManyRequests
+    }.freeze
+    private_constant :STATUS_MAP
+
+    # Build the right error subclass for the given HTTP status + response
+    # body. Always returns an instance of {VeryfiError} or one of its
+    # subclasses; never raises.
+    #
+    # @param status   [Integer]                       HTTP status code
+    # @param response [Hash, Veryfi::Resource, nil]   parsed JSON body
+    # @return [VeryfiError]
+    def self.from_response(status, response)
+      klass = error_class_for(status)
+      message = format_message(status, response)
+
+      klass.new(message, response, status)
+    end
+
+    def self.error_class_for(status)
+      return STATUS_MAP[status] if STATUS_MAP.key?(status)
+      return ServerError        if status.between?(500, 599)
+      return ClientError        if status.between?(400, 499)
+
+      VeryfiError
+    end
+    private_class_method :error_class_for
+
+    def self.format_message(status, response)
+      if response.nil? || response.empty?
+        format("%<code>d", code: status)
+      else
+        format("%<code>d, %<message>s", code: status, message: response["error"])
+      end
+    end
+    private_class_method :format_message
   end
 end

data/lib/veryfi/request.rb

@@ -5,8 +5,16 @@ require "faraday"
 require "json"
 
 module Veryfi
+  # Low-level HTTP layer used by every API class. You typically don't need
+  # to interact with this directly — go through {Veryfi::Client} instead.
+  #
+  # Custom Faraday configuration (adapter, retries, logging, persistent
+  # connections, …) can be supplied via the `faraday:` block when
+  # constructing the client. The block receives the `Faraday::Connection`
+  # before it's frozen, so you can attach any middleware you want.
   class Request
-    attr_reader :client_id, :client_secret, :username, :api_key, :base_url, :api_version, :timeout
+    attr_reader :client_id, :client_secret, :username, :api_key,
+                :base_url, :api_version, :timeout, :faraday_block
 
     VERBS_WITH_BODIES = %i[post put].freeze
 
@@ -17,7 +25,8 @@ module Veryfi
       api_key,
       base_url,
       api_version,
-      timeout
+      timeout,
+      faraday_block = nil
     )
       @client_id = client_id
       @client_secret = client_secret
@@ -26,6 +35,7 @@ module Veryfi
       @base_url = base_url
       @api_version = api_version
       @timeout = timeout
+      @faraday_block = faraday_block
     end
 
     def get(path, params = {})
@@ -68,6 +78,7 @@ module Veryfi
     def conn
       @_conn ||= Faraday.new do |conn|
         conn.options.timeout = timeout
+        faraday_block&.call(conn)
       end
     end
 
@@ -84,18 +95,18 @@ module Veryfi
       signature = generate_signature(params, timestamp)
 
       default_headers.merge(
-        "X-Veryfi-Request-Timestamp": timestamp,
-        "X-Veryfi-Request-Signature": signature
+        "X-Veryfi-Request-Timestamp" => timestamp,
+        "X-Veryfi-Request-Signature" => signature
       )
     end
 
     def default_headers
       {
-        "User-Agent": "Ruby Veryfi-Ruby/#{Veryfi::VERSION}",
-        Accept: "application/json",
-        "Content-Type": "application/json",
-        "Client-Id": client_id,
-        Authorization: "apikey #{username}:#{api_key}"
+        "User-Agent" => "Ruby Veryfi-Ruby/#{Veryfi::VERSION}",
+        "Accept" => "application/json",
+        "Content-Type" => "application/json",
+        "Client-Id" => client_id,
+        "Authorization" => "apikey #{username}:#{api_key}"
       }
     end
 
@@ -104,9 +115,9 @@ module Veryfi
     end
 
     def process_response(response)
-      return {} if response.body.empty?
+      return Veryfi::Resource.new if response.body.empty?
 
-      JSON.parse(response.body)
+      Veryfi::Resource.wrap(JSON.parse(response.body))
     end
   end
 end

data/lib/veryfi/resource.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Veryfi
+  # A lightweight, dependency-free wrapper around an API response payload.
+  #
+  # `Resource` inherits from `Hash`, so anything that already treats the
+  # response as a hash keeps working unchanged:
+  #
+  #   response["id"]            # => 44691518
+  #   response.dig("vendor", "name")
+  #   response.is_a?(Hash)      # => true
+  #   JSON.pretty_generate(response)
+  #
+  # In addition, every key is also accessible as a method, recursively:
+  #
+  #   response.id               # => 44691518
+  #   response.vendor.name      # => "East Repair"
+  #   response.line_items.first.description
+  #   response.is_duplicate?    # => truthiness of self["is_duplicate"]
+  #
+  # Nested hashes are wrapped into Resources, and arrays of hashes become
+  # arrays of Resources. Other values (strings, numbers, booleans, nil)
+  # pass through untouched. Both string (`"id"`) and symbol (`:id`) keys
+  # work transparently.
+  class Resource < ::Hash
+    # Wrap any value coming back from the API. Hashes become Resources,
+    # arrays are mapped recursively, and everything else passes through.
+    #
+    # @param value [Object] raw value from `JSON.parse`
+    # @return [Object] wrapped value
+    def self.wrap(value)
+      return value if value.is_a?(Resource)
+
+      case value
+      when ::Hash  then new(value)
+      when ::Array then value.map { |v| wrap(v) }
+      else              value
+      end
+    end
+
+    def initialize(hash = {})
+      super()
+      hash.each_pair { |key, value| self[key.to_s] = Resource.wrap(value) }
+    end
+
+    def [](key)
+      super(key.to_s)
+    end
+
+    # rubocop:disable Style/ArgumentsForwarding -- keep explicit forwarding for clarity and Ruby 3.0 portability
+    def fetch(key, *args, &block)
+      super(key.to_s, *args, &block)
+    end
+    # rubocop:enable Style/ArgumentsForwarding
+
+    def key?(key)
+      super(key.to_s)
+    end
+    alias has_key? key?
+    alias include? key?
+    alias member? key?
+
+    # Returns a plain (unwrapped) `Hash` representation, recursively.
+    # Useful when you need to hand the data off to something that explicitly
+    # expects a plain Hash (e.g. some serializers).
+    #
+    # @return [Hash]
+    def to_h
+      each_with_object({}) do |(key, value), memo|
+        memo[key] = unwrap(value)
+      end
+    end
+    alias to_hash to_h
+
+    def respond_to_missing?(name, include_private = false)
+      string_name = name.to_s.chomp("?")
+      key?(string_name) || super
+    end
+
+    def method_missing(name, *args, &block)
+      string_name = name.to_s
+      bare_name = string_name.chomp("?")
+
+      if args.empty? && block.nil? && key?(bare_name)
+        value = self[bare_name]
+        string_name.end_with?("?") ? !value.nil? && value != false : value
+      else
+        super
+      end
+    end
+
+    private
+
+    def unwrap(value)
+      case value
+      when Resource then value.to_h
+      when ::Array  then value.map { |v| v.is_a?(Resource) ? v.to_h : v }
+      else               value
+      end
+    end
+  end
+end

data/lib/veryfi/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Veryfi
-  VERSION = "3.0.0"
+  VERSION = "4.0.0"
 end