veryfi 3.0.0 → 4.0.1

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: 30,
+      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     = 30
+    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 = {})
@@ -54,8 +64,7 @@ module Veryfi
       url = [api_url, path].join
       body = generate_body(http_verb, params)
       headers = generate_headers(params)
-
-      response = conn.public_send(http_verb, url, body, headers)
+      response = attempt_request(http_verb, url, body, headers)
       json_response = process_response(response)
 
       if response.success?
@@ -65,9 +74,19 @@ module Veryfi
       end
     end
 
+    def attempt_request(http_verb, url, body, headers)
+      conn.public_send(http_verb, url, body, headers)
+    rescue Faraday::TimeoutError => e
+      raise unless e.message.include?("closed")
+
+      @_conn = nil
+      conn.public_send(http_verb, url, body, headers)
+    end
+
     def conn
       @_conn ||= Faraday.new do |conn|
         conn.options.timeout = timeout
+        faraday_block&.call(conn)
       end
     end
 
@@ -84,18 +103,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 +123,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