veryfi 3.0.0 → 4.0.0

data/lib/veryfi/api/document.rb

@@ -4,7 +4,14 @@ require "base64"
 
 module Veryfi
   module Api
+    # Receipts & invoices endpoints (`/partner/documents/`).
+    #
+    # @see https://docs.veryfi.com/api/receipts-invoices/
     class Document
+      # Default categories sent with `process` / `process_url` when the
+      # caller does not supply their own `:categories` list. Veryfi will
+      # bucket the document into one of these values for the `category`
+      # field on the response.
       CATEGORIES = [
         "Advertising & Marketing",
         "Automotive",
@@ -29,10 +36,63 @@ module Veryfi
         @request = request
       end
 
+      # List previously processed documents.
+      #
+      # @see https://docs.veryfi.com/api/receipts-invoices/search-documents/
+      #
+      # @param params [Hash] query-string parameters (all optional)
+      # @option params [String]  :q              free-text search query
+      # @option params [String]  :external_id    filter by your own document id
+      # @option params [String]  :tag            filter by tag name
+      # @option params [String]  :created__gt    "YYYY-MM-DD HH:MM:SS" — strictly after
+      # @option params [String]  :created__gte   "YYYY-MM-DD HH:MM:SS" — after or equal
+      # @option params [String]  :created__lt    "YYYY-MM-DD HH:MM:SS" — strictly before
+      # @option params [String]  :created__lte   "YYYY-MM-DD HH:MM:SS" — before or equal
+      # @option params [Integer] :page           1-indexed page number (default 1)
+      # @option params [Integer] :page_size      items per page (default 50)
+      #
+      # @return [Veryfi::Resource] `{ "documents" => [...] }`
       def all(params = {})
         request.get("/partner/documents/", params)
       end
 
+      # Upload a local file and extract its data.
+      #
+      # Required:
+      #   * `:file_path` — path on disk to the file to process.
+      #
+      # All other keys below are optional. **Omitting a key is equivalent to
+      # passing its default value** — both produce the same API call. Pass a
+      # key explicitly only when you want a non-default value or when you
+      # want to make the intent explicit in your code.
+      #
+      # @see https://docs.veryfi.com/api/receipts-invoices/process-a-document/
+      #
+      # @param raw_params [Hash]
+      # @option raw_params [String]        :file_path   **required.** Local path to the file.
+      # @option raw_params [String]        :file_name   (basename of `:file_path`, extension stripped)
+      #   Display name sent to Veryfi.
+      # @option raw_params [Array<String>] :categories  ({CATEGORIES})
+      #   Restrict Veryfi's categorization to this set.
+      # @option raw_params [Array<String>] :tags        (`nil`)
+      #   Tags to attach to the resulting document.
+      # @option raw_params [Boolean]       :auto_delete (`false`)
+      #   If true, delete from Veryfi storage right after extraction.
+      # @option raw_params [Boolean]       :boost_mode  (`false`)
+      #   Skip data enrichment for faster, less-accurate processing.
+      # @option raw_params [Boolean]       :async       (`false`)
+      #   Return immediately; the document keeps processing server-side.
+      #   Prefer the dedicated async endpoint where available.
+      # @option raw_params [String]        :external_id (`nil`)
+      #   Your own identifier to associate with the document.
+      # @option raw_params [Integer]       :max_pages_to_process (`nil` = all pages)
+      #   Cap pages read, starting from page 1.
+      # @option raw_params [Hash]          :bounding_boxes     (`false`)
+      #   Return bounding-box info for extracted fields.
+      # @option raw_params [Hash]          :confidence_details (`false`)
+      #   Return confidence score details.
+      #
+      # @return [Veryfi::Resource] Extracted document data.
       def process(raw_params)
         params = setup_create_params(raw_params)
 
@@ -48,20 +108,77 @@ module Veryfi
         request.post("/partner/documents/", payload)
       end
 
+      # Process a document from a public URL.
+      #
+      # Either `:file_url` (single) or `:file_urls` (multiple, processed as
+      # one logical document) must be present. All other params behave the
+      # same as in {#process}.
+      #
+      # @see https://docs.veryfi.com/api/receipts-invoices/process-a-document/
+      #
+      # @param raw_params [Hash]
+      # @option raw_params [String]         :file_url    publicly accessible URL to a single file
+      # @option raw_params [Array<String>]  :file_urls   list of publicly accessible URLs
+      # @option raw_params [Array<String>]  :categories  ({CATEGORIES})
+      # @option raw_params [Array<String>]  :tags        (`nil`)
+      # @option raw_params [Boolean]        :auto_delete (`false`)
+      # @option raw_params [Boolean]        :boost_mode  (`false`)
+      # @option raw_params [Boolean]        :async       (`false`)
+      # @option raw_params [String]         :external_id (`nil`)
+      # @option raw_params [Integer]        :max_pages_to_process (`nil` = all pages)
+      #
+      # @return [Veryfi::Resource]
       def process_url(raw_params)
         params = setup_create_params(raw_params)
 
         request.post("/partner/documents/", params)
       end
 
+      # Bulk-process many documents from URLs in a single call.
+      #
+      # @see https://docs.veryfi.com/api/receipts-invoices/bulk-process-multiple-documents/
+      # @note This endpoint must be enabled for your account. Contact support@veryfi.com.
+      #
+      # @param file_urls [Array<String>] publicly accessible URLs
+      # @return [Veryfi::Resource] `{ "document_ids" => [...] }`
+      def process_bulk(file_urls)
+        request.post("/partner/documents/bulk/", file_urls: file_urls)
+      end
+
+      # Fetch a single document by id.
+      #
+      # @see https://docs.veryfi.com/api/receipts-invoices/get-a-document/
+      #
+      # @param id [Integer] document id
+      # @param params [Hash] query-string parameters (all optional)
+      # @option params [Boolean] :bounding_boxes      (`false`) Include bounding boxes in the response.
+      # @option params [Boolean] :confidence_details  (`false`) Include per-field confidence scores.
+      #
+      # @return [Veryfi::Resource]
       def get(id, params = {})
         request.get("/partner/documents/#{id}", params)
       end
 
+      # Update writable fields on a previously processed document.
+      #
+      # @example
+      #   client.document.update(44_691_518, date: "2021-01-01", notes: "look what I did")
+      #
+      # @see https://docs.veryfi.com/api/receipts-invoices/update-a-document/
+      #
+      # @param id [Integer] document id
+      # @param params [Hash] any writable fields you want to change
+      # @return [Veryfi::Resource] the updated document
       def update(id, params)
         request.put("/partner/documents/#{id}", params)
       end
 
+      # Delete a document.
+      #
+      # @see https://docs.veryfi.com/api/receipts-invoices/delete-a-document/
+      #
+      # @param id [Integer]
+      # @return [Veryfi::Resource] `{ "status" => "ok", "message" => "..." }`
       def delete(id)
         request.delete("/partner/documents/#{id}")
       end

data/lib/veryfi/api/document_tag.rb

@@ -2,6 +2,9 @@
 
 module Veryfi
   module Api
+    # Tags on a specific document (`/partner/documents/{id}/tags/`).
+    #
+    # @see https://docs.veryfi.com/api/receipts-invoices/get-document-tags/
     class DocumentTag
       attr_reader :request
 
@@ -9,20 +12,60 @@ module Veryfi
         @request = request
       end
 
+      # List tags on a document.
+      #
+      # @param document_id [Integer]
+      # @param params [Hash] optional query-string parameters
+      # @return [Array<Veryfi::Resource>] the `"tags"` array from the response
       def all(document_id, params = {})
         response = request.get("/partner/documents/#{document_id}/tags/", params)
 
         response["tags"]
       end
 
+      # Add a single tag to a document. (PUT semantics — creates the tag if
+      # it does not exist, otherwise links the existing tag.)
+      #
+      # @param document_id [Integer]
+      # @param params [Hash]
+      # @option params [String] :name **required.** Tag name.
+      # @return [Veryfi::Resource] the linked tag
       def add(document_id, params)
         request.put("/partner/documents/#{document_id}/tags/", params)
       end
 
+      # Add many tags to a document in a single call.
+      #
+      # @param document_id [Integer]
+      # @param tags [Array<String>] tag names
+      # @return [Veryfi::Resource] `{ "tags" => [...] }`
+      def add_multiple(document_id, tags)
+        request.post("/partner/documents/#{document_id}/tags/", tags: tags)
+      end
+
+      # Replace the entire tag list on a document (PUT on the parent
+      # resource with a `tags:` array).
+      #
+      # @param document_id [Integer]
+      # @param tags [Array<String>] new full list of tag names
+      # @return [Veryfi::Resource] the updated document
+      def replace(document_id, tags)
+        request.put("/partner/documents/#{document_id}/", tags: tags)
+      end
+
+      # Unlink every tag from a document.
+      #
+      # @param document_id [Integer]
+      # @return [Veryfi::Resource]
       def delete_all(document_id)
         request.delete("/partner/documents/#{document_id}/tags/")
       end
 
+      # Unlink a single tag from a document.
+      #
+      # @param document_id [Integer]
+      # @param id [Integer] tag id
+      # @return [Veryfi::Resource]
       def delete(document_id, id)
         request.delete("/partner/documents/#{document_id}/tags/#{id}")
       end

data/lib/veryfi/api/file_payload.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module Veryfi
+  module Api
+    # Mix-in providing a small helper to turn a local file path into the
+    # `{ file_name:, file_data: }` payload that all of Veryfi's "process"
+    # endpoints expect.
+    module FilePayload
+      private
+
+      def file_payload(file_path, file_name = nil)
+        encoded = Base64.encode64(File.read(file_path)).gsub("\n", "")
+
+        {
+          file_name: file_name || File.basename(file_path),
+          file_data: encoded
+        }
+      end
+    end
+  end
+end

data/lib/veryfi/api/line_item.rb

@@ -2,6 +2,9 @@
 
 module Veryfi
   module Api
+    # Line items on a processed document (`/partner/documents/{id}/line-items/`).
+    #
+    # @see https://docs.veryfi.com/api/receipts-invoices/get-document-line-items/
     class LineItem
       attr_reader :request
 
@@ -9,26 +12,78 @@ module Veryfi
         @request = request
       end
 
+      # List all line items on a document.
+      #
+      # @param document_id [Integer]
+      # @param params [Hash] optional query-string parameters
+      # @return [Array<Veryfi::Resource>] line items (the `"line_items"` array from the response)
       def all(document_id, params = {})
         response = request.get("/partner/documents/#{document_id}/line-items/", params)
         response["line_items"]
       end
 
+      # Add a line item to an existing document.
+      #
+      # @see https://docs.veryfi.com/api/receipts-invoices/create-a-line-item/
+      #
+      # @param document_id [Integer]
+      # @param params [Hash] line-item body. Common fields:
+      # @option params [String]  :description     **required.** Free-text description.
+      # @option params [Numeric] :total           **required.** Line total.
+      # @option params [Numeric] :quantity        (`1`)
+      # @option params [Numeric] :price           Unit price.
+      # @option params [Numeric] :tax             Tax amount.
+      # @option params [Numeric] :tax_rate        Tax rate (%).
+      # @option params [Numeric] :discount        Discount amount.
+      # @option params [String]  :sku             SKU / product code.
+      # @option params [String]  :type            "product" / "service" / "fuel" / ...
+      # @option params [String]  :unit_of_measure
+      # @option params [Integer] :order           Display order (0-indexed).
+      # @return [Veryfi::Resource] the created line item
       def create(document_id, params)
         request.post("/partner/documents/#{document_id}/line-items/", params)
       end
 
+      # Fetch a single line item.
+      #
+      # @param document_id [Integer]
+      # @param id [Integer] line item id
+      # @param params [Hash] optional query-string parameters
+      # @return [Veryfi::Resource]
       def get(document_id, id, params = {})
         request.get("/partner/documents/#{document_id}/line-items/#{id}", params)
       end
 
+      # Update a line item.
+      #
+      # @see https://docs.veryfi.com/api/receipts-invoices/update-a-line-item/
+      #
+      # @param document_id [Integer]
+      # @param id [Integer]
+      # @param params [Hash] writable fields you want to change
+      # @return [Veryfi::Resource] the updated line item
       def update(document_id, id, params)
         request.put("/partner/documents/#{document_id}/line-items/#{id}", params)
       end
 
+      # Delete a single line item.
+      #
+      # @param document_id [Integer]
+      # @param id [Integer]
+      # @return [Veryfi::Resource] `{ "status" => "ok", "message" => "..." }`
       def delete(document_id, id)
         request.delete("/partner/documents/#{document_id}/line-items/#{id}")
       end
+
+      # Delete every line item on a document.
+      #
+      # @see https://docs.veryfi.com/api/receipts-invoices/delete-all-document-line-items/
+      #
+      # @param document_id [Integer]
+      # @return [Veryfi::Resource]
+      def delete_all(document_id)
+        request.delete("/partner/documents/#{document_id}/line-items")
+      end
     end
   end
 end

data/lib/veryfi/api/pdf_split.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Veryfi
+  module Api
+    # PDF splitting endpoints (`/partner/documents-set/`).
+    #
+    # Use these when you have a single PDF containing multiple receipts /
+    # invoices. Veryfi will split it and process each page as its own
+    # {Document}; you receive a collection that references the individual
+    # document ids it produced.
+    #
+    # @see https://docs.veryfi.com/api/receipts-invoices/split-and-process-a-pdf/
+    class PdfSplit
+      include FilePayload
+
+      ENDPOINT = "/partner/documents-set/"
+
+      attr_reader :request
+
+      def initialize(request)
+        @request = request
+      end
+
+      # List previously processed document sets.
+      #
+      # @param params [Hash] optional query-string parameters
+      # @return [Veryfi::Resource]
+      def all(params = {})
+        request.get(ENDPOINT, params)
+      end
+
+      # Fetch a single document 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-document PDF 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`)
+      # @option raw_params [Array<String>] :categories (`[]`) Restrict categorization to these values.
+      # @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)
+        params[:categories] ||= []
+
+        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`)
+      # @option raw_params [Array<String>] :categories (`[]`)
+      # @option raw_params [Integer]       :max_pages_to_process (`nil`)
+      # @return [Veryfi::Resource]
+      def process_url(raw_params)
+        params = raw_params.transform_keys(&:to_sym)
+        params[:categories] ||= []
+
+        request.post(ENDPOINT, params)
+      end
+    end
+  end
+end

data/lib/veryfi/api/tag.rb

@@ -2,6 +2,12 @@
 
 module Veryfi
   module Api
+    # Global tag catalog (`/partner/tags/`).
+    #
+    # Note: This endpoint is not present in every Veryfi API version. For
+    # managing tags on a specific document use {Veryfi::Api::DocumentTag}
+    # (or the `.tags` / `.add_tag` / `.add_tags` / `.delete_tag` methods
+    # on each processed-document resource — see {TagOperations}).
     class Tag
       attr_reader :request
 
@@ -9,12 +15,20 @@ module Veryfi
         @request = request
       end
 
+      # List every tag known to the account.
+      #
+      # @param params [Hash] optional query-string parameters
+      # @return [Array<Veryfi::Resource>] the `"tags"` array from the response
       def all(params = {})
         response = request.get("/partner/tags/", params)
 
         response["tags"]
       end
 
+      # Delete a tag by id.
+      #
+      # @param id [Integer]
+      # @return [Veryfi::Resource]
       def delete(id)
         request.delete("/partner/tags/#{id}")
       end

data/lib/veryfi/api/tag_operations.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Veryfi
+  module Api
+    # Mix-in providing the standard per-resource tag endpoints used by
+    # processed-document resources (Any Document, Bank Statement, Business
+    # Card, Check, W-2, W-8, W-9). Each host must define an `ENDPOINT`
+    # constant pointing at the resource collection (e.g. `"/partner/checks/"`).
+    #
+    # When included, the host class exposes:
+    #
+    #   - `#tags(id, params = {})`     → GET `…/{id}/tags`
+    #   - `#add_tag(id, params)`       → PUT `…/{id}/tags`        (single)
+    #   - `#add_tags(id, tags)`        → POST `…/{id}/tags`       (multiple)
+    #   - `#delete_tag(id, tag_id)`    → DELETE `…/{id}/tags/{tag_id}`
+    #   - `#delete_tags(id)`           → DELETE `…/{id}/tags`     (all)
+    module TagOperations
+      # List tags on the resource.
+      #
+      # @param id [Integer] resource id
+      # @param params [Hash] optional query-string parameters
+      # @return [Veryfi::Resource] `{ "tags" => [...] }`
+      def tags(id, params = {})
+        request.get("#{self.class::ENDPOINT}#{id}/tags", params)
+      end
+
+      # Add (or link) a single tag.
+      #
+      # @param id [Integer] resource id
+      # @param params [Hash] e.g. `{ name: "priority" }`
+      # @return [Veryfi::Resource] the linked tag
+      def add_tag(id, params)
+        request.put("#{self.class::ENDPOINT}#{id}/tags", params)
+      end
+
+      # Add many tags in a single call.
+      #
+      # @param id [Integer] resource id
+      # @param tags [Array<String>] tag names
+      # @return [Veryfi::Resource] `{ "tags" => [...] }`
+      def add_tags(id, tags)
+        request.post("#{self.class::ENDPOINT}#{id}/tags", tags: tags)
+      end
+
+      # Unlink a single tag from the resource.
+      #
+      # @param id [Integer] resource id
+      # @param tag_id [Integer]
+      # @return [Veryfi::Resource]
+      def delete_tag(id, tag_id)
+        request.delete("#{self.class::ENDPOINT}#{id}/tags/#{tag_id}")
+      end
+
+      # Unlink every tag from the resource.
+      #
+      # @param id [Integer] resource id
+      # @return [Veryfi::Resource]
+      def delete_tags(id)
+        request.delete("#{self.class::ENDPOINT}#{id}/tags")
+      end
+    end
+  end
+end

data/lib/veryfi/api/tax_line.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Veryfi
+  module Api
+    # Tax lines on a processed document
+    # (`/partner/documents/{id}/tax-lines`).
+    #
+    # Most documents have at most a handful of tax lines (e.g. one for state
+    # sales tax, one for local). This namespace lets you list, add, edit
+    # and remove them on demand.
+    class TaxLine
+      attr_reader :request
+
+      def initialize(request)
+        @request = request
+      end
+
+      # List the tax lines for a document.
+      #
+      # @param document_id [Integer]
+      # @param params [Hash] optional query-string parameters
+      # @return [Veryfi::Resource] `{ "tax_lines" => [...] }`
+      def all(document_id, params = {})
+        request.get("/partner/documents/#{document_id}/tax-lines", params)
+      end
+
+      # Create a tax line on a document.
+      #
+      # @param document_id [Integer]
+      # @param params [Hash]
+      # @option params [String]  :name   **required.** e.g. "Sales Tax".
+      # @option params [Numeric] :rate   Tax rate (%).
+      # @option params [Numeric] :base   Taxable base amount.
+      # @option params [Numeric] :total  Tax amount.
+      # @option params [Integer] :order  Display order (0-indexed).
+      # @return [Veryfi::Resource] the created tax line
+      def create(document_id, params)
+        request.post("/partner/documents/#{document_id}/tax-lines", params)
+      end
+
+      # Fetch a single tax line.
+      #
+      # @param document_id [Integer]
+      # @param id [Integer]
+      # @param params [Hash] optional query-string parameters
+      # @return [Veryfi::Resource]
+      def get(document_id, id, params = {})
+        request.get("/partner/documents/#{document_id}/tax-lines/#{id}", params)
+      end
+
+      # Update a tax line.
+      #
+      # @param document_id [Integer]
+      # @param id [Integer]
+      # @param params [Hash] writable fields you want to change
+      # @return [Veryfi::Resource]
+      def update(document_id, id, params)
+        request.put("/partner/documents/#{document_id}/tax-lines/#{id}", params)
+      end
+
+      # Delete a tax line.
+      #
+      # @param document_id [Integer]
+      # @param id [Integer]
+      # @return [Veryfi::Resource]
+      def delete(document_id, id)
+        request.delete("/partner/documents/#{document_id}/tax-lines/#{id}")
+      end
+    end
+  end
+end

data/lib/veryfi/api/w2.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Veryfi
+  module Api
+    # W-2 endpoints (`/partner/w2s/`).
+    #
+    # @see https://docs.veryfi.com/api/w2s/
+    class W2
+      include FilePayload
+      include TagOperations
+
+      ENDPOINT = "/partner/w2s/"
+
+      attr_reader :request
+
+      def initialize(request)
+        @request = request
+      end
+
+      # List previously processed W-2 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-2 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-2 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-2.
+      #
+      # @param id [Integer]
+      # @param params [Hash]
+      # @return [Veryfi::Resource]
+      def update(id, params)
+        request.put("#{ENDPOINT}#{id}/", params)
+      end
+
+      # Delete a W-2.
+      #
+      # @param id [Integer]
+      # @return [Veryfi::Resource]
+      def delete(id)
+        request.delete("#{ENDPOINT}#{id}/")
+      end
+    end
+  end
+end