veryfi 3.0.0 → 4.0.0

data/lib/veryfi/api/any_document.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Veryfi
+  module Api
+    # Any Document (a-doc) endpoints (`/partner/any-documents/`).
+    #
+    # An A-Doc is a custom document type, defined by a *blueprint* you
+    # configure in Veryfi. Every "process" call must therefore include a
+    # `:blueprint_name`.
+    #
+    # @see https://docs.veryfi.com/api/anydocs/
+    class AnyDocument
+      include FilePayload
+      include TagOperations
+
+      ENDPOINT = "/partner/any-documents/"
+      ASYNC_ENDPOINT = "/partner/any-documents/async"
+
+      attr_reader :request
+
+      def initialize(request)
+        @request = request
+      end
+
+      # List previously processed A-Docs.
+      #
+      # @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 A-Doc 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 file and extract its fields using the given blueprint.
+      #
+      # @param raw_params [Hash]
+      # @option raw_params [String] :blueprint_name **required.** Blueprint id to apply.
+      # @option raw_params [String] :file_path      **required.** Local path to the file.
+      # @option raw_params [String] :file_name      (basename of `:file_path`)
+      # @return [Veryfi::Resource]
+      def process(raw_params)
+        params = raw_params.transform_keys(&:to_sym)
+        blueprint_name = params.delete(:blueprint_name)
+        file_path = params.delete(:file_path)
+        file_name = params.delete(:file_name)
+
+        payload = file_payload(file_path, file_name).merge(blueprint_name: blueprint_name).merge(params)
+
+        request.post(ENDPOINT, payload)
+      end
+
+      # Process an A-Doc from a public URL.
+      #
+      # @param raw_params [Hash]
+      # @option raw_params [String] :blueprint_name **required.**
+      # @option raw_params [String] :file_url       **required** (single URL).
+      # @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
+
+      # Same as {#process} but asynchronous — returns immediately with a
+      # `"status": "processing"` payload while Veryfi runs the extraction
+      # in the background. Use a webhook (or poll {#get}) to learn when the
+      # final result is ready.
+      #
+      # @see https://docs.veryfi.com/api/anydocs/process-a-doc-async/
+      def process_async(raw_params)
+        params = raw_params.transform_keys(&:to_sym)
+        blueprint_name = params.delete(:blueprint_name)
+        file_path = params.delete(:file_path)
+        file_name = params.delete(:file_name)
+
+        payload = file_payload(file_path, file_name).merge(blueprint_name: blueprint_name).merge(params)
+
+        request.post(ASYNC_ENDPOINT, payload)
+      end
+
+      # URL variant of {#process_async}.
+      def process_url_async(raw_params)
+        params = raw_params.transform_keys(&:to_sym)
+        params[:file_name] ||= File.basename(params[:file_url]) if params[:file_url]
+
+        request.post(ASYNC_ENDPOINT, params)
+      end
+
+      # Update writable fields on a processed A-Doc.
+      #
+      # @param id [Integer]
+      # @param params [Hash] writable fields
+      # @return [Veryfi::Resource]
+      def update(id, params)
+        request.put("#{ENDPOINT}#{id}/", params)
+      end
+
+      # Delete an A-Doc.
+      #
+      # @param id [Integer]
+      # @return [Veryfi::Resource]
+      def delete(id)
+        request.delete("#{ENDPOINT}#{id}/")
+      end
+    end
+  end
+end

data/lib/veryfi/api/bank_statement.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Veryfi
+  module Api
+    # Bank Statements endpoints (`/partner/bank-statements/`).
+    #
+    # @see https://docs.veryfi.com/api/bank-statements/
+    class BankStatement
+      include FilePayload
+      include TagOperations
+
+      ENDPOINT = "/partner/bank-statements/"
+      ASYNC_ENDPOINT = "/partner/bank-statements/async"
+
+      attr_reader :request
+
+      def initialize(request)
+        @request = request
+      end
+
+      # List previously processed bank statements.
+      #
+      # @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 bank statement 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 file and extract bank-statement data.
+      #
+      # @param raw_params [Hash]
+      # @option raw_params [String]        :file_path  **required.** Local path.
+      # @option raw_params [String]        :file_name  (basename of `:file_path`)
+      # @option raw_params [Array<String>] :categories (`nil`) Optional categories used to classify
+      #   transactions, e.g. `["Transfer", "Credit Card Payments"]`.
+      # @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.** Publicly accessible URL.
+      # @option raw_params [String]        :file_name  (basename of `:file_url`)
+      # @option raw_params [Array<String>] :categories (`nil`)
+      # @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
+
+      # Async variant of {#process} — returns immediately while Veryfi
+      # extracts the data in the background.
+      def process_async(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(ASYNC_ENDPOINT, payload)
+      end
+
+      # Async variant of {#process_url}.
+      def process_url_async(raw_params)
+        params = raw_params.transform_keys(&:to_sym)
+        params[:file_name] ||= File.basename(params[:file_url]) if params[:file_url]
+
+        request.post(ASYNC_ENDPOINT, params)
+      end
+
+      # Update writable fields on a processed bank statement.
+      #
+      # @param id [Integer]
+      # @param params [Hash]
+      # @return [Veryfi::Resource]
+      def update(id, params)
+        request.put("#{ENDPOINT}#{id}/", params)
+      end
+
+      # Delete a bank statement.
+      #
+      # @param id [Integer]
+      # @return [Veryfi::Resource]
+      def delete(id)
+        request.delete("#{ENDPOINT}#{id}/")
+      end
+    end
+  end
+end

data/lib/veryfi/api/bank_statement_split.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Veryfi
+  module Api
+    # Bank-statement splitting endpoints (`/partner/bank-statements-set/`).
+    #
+    # Use these when you have a single file containing multiple bank
+    # statements (e.g. an annual archive PDF). Veryfi will split the file
+    # and process each statement separately; you receive a collection that
+    # references the individual {BankStatement} ids it produced.
+    class BankStatementSplit
+      include FilePayload
+
+      ENDPOINT = "/partner/bank-statements-set/"
+
+      attr_reader :request
+
+      def initialize(request)
+        @request = request
+      end
+
+      # List previously processed bank-statement sets.
+      #
+      # @param params [Hash] optional query-string parameters
+      # @return [Veryfi::Resource]
+      def all(params = {})
+        request.get(ENDPOINT, params)
+      end
+
+      # Fetch a single bank-statement 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-statement 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 to `:file_url`)
+      # @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/business_card.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Veryfi
+  module Api
+    # Business Cards endpoints (`/partner/business-cards/`).
+    #
+    # @see https://docs.veryfi.com/api/business-cards/
+    class BusinessCard
+      include FilePayload
+      include TagOperations
+
+      ENDPOINT = "/partner/business-cards/"
+
+      attr_reader :request
+
+      def initialize(request)
+        @request = request
+      end
+
+      # List previously processed business cards.
+      #
+      # @param params [Hash] optional query-string parameters
+      # @return [Veryfi::Resource] `{ "documents" => [...] }`
+      def all(params = {})
+        request.get(ENDPOINT, params)
+      end
+
+      # Fetch a single business card 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 an image of a business card and extract its contact 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 business card.
+      #
+      # @param id [Integer]
+      # @param params [Hash] writable fields
+      # @return [Veryfi::Resource]
+      def update(id, params)
+        request.put("#{ENDPOINT}#{id}/", params)
+      end
+
+      # Delete a business card.
+      #
+      # @param id [Integer]
+      # @return [Veryfi::Resource]
+      def delete(id)
+        request.delete("#{ENDPOINT}#{id}/")
+      end
+    end
+  end
+end

data/lib/veryfi/api/check.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Veryfi
+  module Api
+    # Checks endpoints (`/partner/checks/` and
+    # `/partner/check-with-document/` for combined check + remittance
+    # extraction).
+    #
+    # @see https://docs.veryfi.com/api/checks/
+    class Check
+      include FilePayload
+      include TagOperations
+
+      ENDPOINT = "/partner/checks/"
+      REMITTANCE_ENDPOINT = "/partner/check-with-document/"
+      ASYNC_ENDPOINT = "/partner/checks/async"
+
+      attr_reader :request
+
+      def initialize(request)
+        @request = request
+      end
+
+      # List previously processed checks.
+      #
+      # @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 check 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 check image 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)
+        request.post(ENDPOINT, build_file_payload(raw_params))
+      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 to `:file_url`)
+      # @return [Veryfi::Resource]
+      def process_url(raw_params)
+        request.post(ENDPOINT, raw_params.transform_keys(&:to_sym))
+      end
+
+      # Process a check together with its remittance/stub document.
+      # Veryfi will OCR both halves and return a single combined response.
+      #
+      # @see https://docs.veryfi.com/api/checks/process-a-check-with-remittance/
+      #
+      # @param raw_params [Hash]
+      # @option raw_params [String] :file_path **required.**
+      # @option raw_params [String] :file_name (basename of `:file_path`)
+      # @return [Veryfi::Resource]
+      def process_with_remittance(raw_params)
+        request.post(REMITTANCE_ENDPOINT, build_file_payload(raw_params))
+      end
+
+      # URL variant of {#process_with_remittance}.
+      def process_with_remittance_url(raw_params)
+        request.post(REMITTANCE_ENDPOINT, raw_params.transform_keys(&:to_sym))
+      end
+
+      # Async variant of {#process} — returns immediately while Veryfi
+      # processes the check in the background.
+      def process_async(raw_params)
+        request.post(ASYNC_ENDPOINT, build_file_payload(raw_params))
+      end
+
+      # Async variant of {#process_url}.
+      def process_url_async(raw_params)
+        request.post(ASYNC_ENDPOINT, raw_params.transform_keys(&:to_sym))
+      end
+
+      # Update writable fields on a processed check.
+      #
+      # @example
+      #   client.check.update(check_id, notes: "needs review")
+      #
+      # @param id [Integer]
+      # @param params [Hash]
+      # @return [Veryfi::Resource]
+      def update(id, params)
+        request.put("#{ENDPOINT}#{id}/", params)
+      end
+
+      # Delete a check.
+      #
+      # @param id [Integer]
+      # @return [Veryfi::Resource]
+      def delete(id)
+        request.delete("#{ENDPOINT}#{id}/")
+      end
+
+      private
+
+      def build_file_payload(raw_params)
+        params = raw_params.transform_keys(&:to_sym)
+        file_path = params.delete(:file_path)
+        file_name = params.delete(:file_name)
+
+        file_payload(file_path, file_name).merge(params)
+      end
+    end
+  end
+end

data/lib/veryfi/api/classify.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Veryfi
+  module Api
+    # Document classification endpoint (`/partner/classify/`).
+    #
+    # Given a file and an optional set of candidate document types,
+    # returns Veryfi's best guess at what kind of document it is (invoice,
+    # receipt, w-2, …) along with confidence scores.
+    #
+    # @see https://docs.veryfi.com/api/classify/classify-a-document/
+    class Classify
+      include FilePayload
+
+      ENDPOINT = "/partner/classify/"
+
+      attr_reader :request
+
+      def initialize(request)
+        @request = request
+      end
+
+      # Upload a local file for classification.
+      #
+      # @param raw_params [Hash]
+      # @option raw_params [String]        :file_path      **required.** Local path.
+      # @option raw_params [String]        :file_name      (basename of `:file_path`)
+      # @option raw_params [Array<String>] :document_types (`nil` = use Veryfi's full default set)
+      #   Restrict the classifier to these document types.
+      # @return [Veryfi::Resource] e.g. `{ "document_type" => "invoice", "score" => 0.98, ... }`
+      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 [Array<String>] :document_types (`nil`)
+      # @return [Veryfi::Resource]
+      def process_url(raw_params)
+        request.post(ENDPOINT, raw_params.transform_keys(&:to_sym))
+      end
+    end
+  end
+end