tabscanner 0.1.0

data/lib/tabscanner/request.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/multipart'
+require 'json'
+
+module Tabscanner
+  # Handles HTTP requests to the Tabscanner API
+  # 
+  # This class manages multipart form data uploads for image processing
+  # and handles all HTTP communication with proper error handling.
+  #
+  # @example Submit a file path
+  #   Request.submit_receipt('/path/to/receipt.jpg')
+  #
+  # @example Submit an IO stream
+  #   File.open('/path/to/receipt.jpg', 'rb') do |file|
+  #     Request.submit_receipt(file)
+  #   end
+  class Request
+    # Submit a receipt image for processing
+    #
+    # @param file_path_or_io [String, IO] Local file path or IO stream containing image data
+    # @return [String] Token for result retrieval
+    # @raise [UnauthorizedError] when API key is invalid (401)
+    # @raise [ValidationError] when request validation fails (422)
+    # @raise [ServerError] when server errors occur (500+)
+    # @raise [Error] for other API errors
+    def self.submit_receipt(file_path_or_io)
+      config = Tabscanner.config
+      config.validate!
+
+      # Handle file input - convert file path to IO if needed
+      file_io, filename = normalize_file_input(file_path_or_io)
+
+      # Build the connection
+      conn = build_connection(config)
+
+      # Make the request
+      response = conn.post('/api/2/process') do |req|
+        req.body = build_multipart_body(file_io, filename)
+      end
+
+      # Debug logging for request/response
+      log_request_response('POST', '/api/2/process', response, config) if config.debug?
+
+      handle_response(response)
+    ensure
+      # Close file if we opened it
+      file_io&.close if file_path_or_io.is_a?(String) && file_io
+    end
+
+    private
+
+    # Normalize file input to IO and filename
+    # @param file_path_or_io [String, IO] File path or IO stream
+    # @return [Array<IO, String>] IO object and filename
+    def self.normalize_file_input(file_path_or_io)
+      if file_path_or_io.is_a?(String)
+        # File path provided
+        raise Error, "File not found: #{file_path_or_io}" unless File.exist?(file_path_or_io)
+        file_io = File.open(file_path_or_io, 'rb')
+        filename = File.basename(file_path_or_io)
+      else
+        # IO stream provided
+        file_io = file_path_or_io
+        filename = file_io.respond_to?(:path) ? File.basename(file_io.path) : 'image'
+      end
+
+      [file_io, filename]
+    end
+
+    # Build Faraday connection with proper configuration
+    # @param config [Config] Configuration instance
+    # @return [Faraday::Connection] Configured connection
+    def self.build_connection(config)
+      base_url = config.base_url || "https://api.tabscanner.com"
+      
+      Faraday.new(url: base_url) do |f|
+        f.request :multipart
+        f.request :url_encoded
+        f.adapter Faraday.default_adapter
+        f.headers['apikey'] = config.api_key
+        f.headers['User-Agent'] = "Tabscanner Ruby Gem #{Tabscanner::VERSION}"
+      end
+    end
+
+    # Build multipart form data for file upload
+    # @param file_io [IO] File IO stream
+    # @param filename [String] Name of the file
+    # @return [Hash] Multipart form data
+    def self.build_multipart_body(file_io, filename)
+      {
+        image: Faraday::UploadIO.new(file_io, mime_type_for_file(filename), filename)
+      }
+    end
+
+    # Determine MIME type for file
+    # @param filename [String] Name of the file
+    # @return [String] MIME type
+    def self.mime_type_for_file(filename)
+      ext = File.extname(filename).downcase
+      case ext
+      when '.jpg', '.jpeg'
+        'image/jpeg'
+      when '.png'
+        'image/png'
+      when '.gif'
+        'image/gif'
+      when '.bmp'
+        'image/bmp'
+      when '.tiff', '.tif'
+        'image/tiff'
+      else
+        'image/jpeg' # Default fallback
+      end
+    end
+
+    # Handle API response and extract token
+    # @param response [Faraday::Response] HTTP response
+    # @return [String] Token from response
+    # @raise [UnauthorizedError, ValidationError, ServerError, Error] Based on status code
+    def self.handle_response(response)
+      raw_response = build_raw_response_data(response)
+      
+      case response.status
+      when 200, 201
+        # Success - parse and return token
+        parse_success_response(response)
+      when 401
+        raise UnauthorizedError.new("Invalid API key or authentication failed", raw_response: raw_response)
+      when 422
+        error_message = parse_error_message(response) || "Request validation failed"
+        raise ValidationError.new(error_message, raw_response: raw_response)
+      when 500..599
+        error_message = parse_error_message(response) || "Server error occurred"
+        raise ServerError.new(error_message, raw_response: raw_response)
+      else
+        error_message = parse_error_message(response) || "Request failed with status #{response.status}"
+        raise Error.new(error_message, raw_response: raw_response)
+      end
+    end
+
+    # Parse successful response to extract token
+    # @param response [Faraday::Response] HTTP response
+    # @return [String] Token value
+    def self.parse_success_response(response)
+      begin
+        data = JSON.parse(response.body)
+        
+        # Check if the API returned an error even with 200 status
+        if data['success'] == false
+          error_message = data['message'] || "API request failed"
+          case data['code']
+          when 401
+            raise UnauthorizedError.new(error_message, raw_response: build_raw_response_data(response))
+          when 422
+            raise ValidationError.new(error_message, raw_response: build_raw_response_data(response))
+          when 500..599
+            raise ServerError.new(error_message, raw_response: build_raw_response_data(response))
+          else
+            raise Error.new(error_message, raw_response: build_raw_response_data(response))
+          end
+        end
+        
+        token = data['token'] || data['id'] || data['request_id']
+        
+        raise Error, "No token found in response" if token.nil? || token.empty?
+        
+        token
+      rescue JSON::ParserError
+        raise Error, "Invalid JSON response from API"
+      end
+    end
+
+    # Parse error message from response
+    # @param response [Faraday::Response] HTTP response
+    # @return [String, nil] Error message if available
+    def self.parse_error_message(response)
+      return nil if response.body.nil? || response.body.empty?
+
+      begin
+        data = JSON.parse(response.body)
+        data['error'] || data['message'] || data['errors']&.first
+      rescue JSON::ParserError
+        # If JSON parsing fails, return raw body if it's short enough
+        response.body.length < 200 ? response.body : nil
+      end
+    end
+
+    # Build raw response data for error debugging
+    # @param response [Faraday::Response] HTTP response
+    # @return [Hash] Raw response data
+    def self.build_raw_response_data(response)
+      {
+        status: response.status,
+        headers: response.headers.to_hash,
+        body: response.body
+      }
+    end
+
+    # Log request and response details for debugging
+    # @param method [String] HTTP method
+    # @param endpoint [String] API endpoint
+    # @param response [Faraday::Response] HTTP response
+    # @param config [Config] Configuration instance
+    def self.log_request_response(method, endpoint, response, config)
+      logger = config.logger
+      
+      # Log request details
+      logger.debug("HTTP Request: #{method.upcase} #{endpoint}")
+      logger.debug("Request Headers: apikey=[REDACTED], User-Agent=#{response.env.request_headers['User-Agent']}")
+      
+      # Log response details
+      logger.debug("HTTP Response: #{response.status}")
+      logger.debug("Response Headers: #{response.headers.to_hash}")
+      
+      # Log response body (truncated if too long)
+      body = response.body
+      if body && body.length > 500
+        logger.debug("Response Body: #{body[0..500]}... (truncated)")
+      else
+        logger.debug("Response Body: #{body}")
+      end
+    end
+  end
+end

data/lib/tabscanner/result.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+
+module Tabscanner
+  # Handles polling for OCR processing results
+  # 
+  # This class manages the polling logic to retrieve processing results
+  # from the Tabscanner API using a token, with retry logic and timeout handling.
+  #
+  # @example Poll for results with default timeout
+  #   Result.get_result('token123')
+  #
+  # @example Poll for results with custom timeout
+  #   Result.get_result('token123', timeout: 30)
+  class Result
+    # Poll for OCR processing results using a token
+    #
+    # @param token [String] Token from submit_receipt call
+    # @param timeout [Integer] Maximum time to wait in seconds (default: 15)
+    # @return [Hash] Parsed receipt data when processing is complete
+    # @raise [UnauthorizedError] when API key is invalid (401)
+    # @raise [ValidationError] when token is invalid (422)
+    # @raise [ServerError] when server errors occur (500+)
+    # @raise [Error] for timeout or other API errors
+    def self.get_result(token, timeout: 15)
+      config = Tabscanner.config
+      config.validate!
+
+      start_time = Time.now
+      conn = build_connection(config)
+
+      config.logger.debug("Starting result polling for token: #{token} (timeout: #{timeout}s)") if config.debug?
+
+      loop do
+        # Check timeout
+        elapsed = Time.now - start_time
+        if elapsed >= timeout
+          raise Error, "Timeout waiting for result after #{timeout} seconds"
+        end
+
+        # Make GET request to result endpoint
+        response = conn.get("/api/result/#{token}")
+        
+        # Debug logging for request/response
+        log_request_response('GET', "/api/result/#{token}", response, config) if config.debug?
+        
+        result = handle_response(response)
+
+        # Check status in response
+        case result['status']
+        when 'complete', 'completed', 'success', 'done'
+          config.logger.debug("Result ready for token: #{token}") if config.debug?
+          return extract_result_data(result)
+        when 'processing', 'pending', 'in_progress'
+          # Wait 1 second before next poll
+          config.logger.debug("Result still processing for token: #{token}, waiting 1s...") if config.debug?
+          sleep 1
+          next
+        when 'failed', 'error'
+          error_message = result['error'] || result['message'] || 'Processing failed'
+          config.logger.debug("Result failed for token: #{token} - #{error_message}") if config.debug?
+          raise Error, error_message
+        else
+          # Unknown status - treat as error
+          config.logger.debug("Unknown status for token: #{token} - #{result['status']}") if config.debug?
+          raise Error, "Unknown processing status: #{result['status']}"
+        end
+      end
+    end
+
+    private
+
+    # Build Faraday connection with proper configuration
+    # @param config [Config] Configuration instance
+    # @return [Faraday::Connection] Configured connection
+    def self.build_connection(config)
+      base_url = config.base_url || "https://api.tabscanner.com"
+      
+      Faraday.new(url: base_url) do |f|
+        f.request :url_encoded
+        f.adapter Faraday.default_adapter
+        f.headers['apikey'] = config.api_key
+        f.headers['User-Agent'] = "Tabscanner Ruby Gem #{Tabscanner::VERSION}"
+        f.headers['Accept'] = 'application/json'
+      end
+    end
+
+    # Handle API response
+    # @param response [Faraday::Response] HTTP response
+    # @return [Hash] Parsed JSON response
+    # @raise [UnauthorizedError, ValidationError, ServerError, Error] Based on status code
+    def self.handle_response(response)
+      raw_response = build_raw_response_data(response)
+      
+      case response.status
+      when 200, 201
+        # Success - parse and return data
+        parse_json_response(response)
+      when 401
+        raise UnauthorizedError.new("Invalid API key or authentication failed", raw_response: raw_response)
+      when 422
+        error_message = parse_error_message(response) || "Invalid token or request"
+        raise ValidationError.new(error_message, raw_response: raw_response)
+      when 500..599
+        error_message = parse_error_message(response) || "Server error occurred"
+        raise ServerError.new(error_message, raw_response: raw_response)
+      else
+        error_message = parse_error_message(response) || "Request failed with status #{response.status}"
+        raise Error.new(error_message, raw_response: raw_response)
+      end
+    end
+
+    # Parse JSON response body
+    # @param response [Faraday::Response] HTTP response
+    # @return [Hash] Parsed JSON data
+    # @raise [Error] if JSON parsing fails
+    def self.parse_json_response(response)
+      JSON.parse(response.body)
+    rescue JSON::ParserError
+      raise Error, "Invalid JSON response from API"
+    end
+
+    # Extract result data from complete response
+    # @param result [Hash] Parsed response data
+    # @return [Hash] Receipt data
+    def self.extract_result_data(result)
+      # Return the full result hash - the actual data structure will depend on the API
+      # Common patterns: result['data'], result['receipt'], or the full result
+      if result.key?('data')
+        result['data']
+      elsif result.key?('receipt')
+        result['receipt']
+      else
+        # Return the full result excluding status metadata
+        result.reject { |k, _| %w[status message timestamp id].include?(k) }
+      end
+    end
+
+    # Parse error message from response
+    # @param response [Faraday::Response] HTTP response  
+    # @return [String, nil] Error message if available
+    def self.parse_error_message(response)
+      return nil if response.body.nil? || response.body.empty?
+
+      begin
+        data = JSON.parse(response.body)
+        data['error'] || data['message'] || data['errors']&.first
+      rescue JSON::ParserError
+        # If JSON parsing fails, return raw body if it's short enough
+        response.body.length < 200 ? response.body : nil
+      end
+    end
+
+    # Build raw response data for error debugging
+    # @param response [Faraday::Response] HTTP response
+    # @return [Hash] Raw response data
+    def self.build_raw_response_data(response)
+      {
+        status: response.status,
+        headers: response.headers.to_hash,
+        body: response.body
+      }
+    end
+
+    # Log request and response details for debugging
+    # @param method [String] HTTP method
+    # @param endpoint [String] API endpoint
+    # @param response [Faraday::Response] HTTP response
+    # @param config [Config] Configuration instance
+    def self.log_request_response(method, endpoint, response, config)
+      logger = config.logger
+      
+      # Log request details
+      logger.debug("HTTP Request: #{method.upcase} #{endpoint}")
+      logger.debug("Request Headers: apikey=[REDACTED], User-Agent=#{response.env.request_headers['User-Agent']}")
+      
+      # Log response details
+      logger.debug("HTTP Response: #{response.status}")
+      logger.debug("Response Headers: #{response.headers.to_hash}")
+      
+      # Log response body (truncated if too long)
+      body = response.body
+      if body && body.length > 500
+        logger.debug("Response Body: #{body[0..500]}... (truncated)")
+      else
+        logger.debug("Response Body: #{body}")
+      end
+    end
+  end
+end

data/lib/tabscanner/version.rb

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

data/lib/tabscanner.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "tabscanner/version"
+require_relative "tabscanner/errors/base_error"
+require_relative "tabscanner/errors/configuration_error"
+require_relative "tabscanner/errors/unauthorized_error"
+require_relative "tabscanner/errors/validation_error"
+require_relative "tabscanner/errors/server_error"
+require_relative "tabscanner/config"
+require_relative "tabscanner/http_client"
+require_relative "tabscanner/request"
+require_relative "tabscanner/result"
+require_relative "tabscanner/client"
+require_relative "tabscanner/credits"
+
+module Tabscanner
+  # Submit a receipt image for OCR processing
+  #
+  # @param file_path_or_io [String, IO] Local file path or IO stream containing image data
+  # @return [String] Token for later result retrieval
+  # @see Client.submit_receipt
+  def self.submit_receipt(file_path_or_io)
+    Client.submit_receipt(file_path_or_io)
+  end
+
+  # Poll for OCR processing results using a token
+  #
+  # @param token [String] Token from submit_receipt call
+  # @param timeout [Integer] Maximum time to wait in seconds (default: 15)
+  # @return [Hash] Parsed receipt data when processing is complete
+  # @see Client.get_result
+  def self.get_result(token, timeout: 15)
+    Client.get_result(token, timeout: timeout)
+  end
+
+  # Check remaining API credits for the authenticated account
+  #
+  # @return [Integer] Number of remaining credits
+  # @see Credits.get_credits
+  def self.get_credits
+    Credits.get_credits
+  end
+end

data/sig/tabscanner.rbs

@@ -0,0 +1,4 @@
+module Tabscanner
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,149 @@
+--- !ruby/object:Gem::Specification
+name: tabscanner
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Forrest Chang
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-07-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-multipart
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+description: A Ruby gem that provides a simple interface for submitting receipt images
+  to the Tabscanner API and retrieving parsed receipt data. Features include automatic
+  polling, comprehensive error handling, debug mode, and environment-based configuration.
+email:
+- fchang@hedgeye.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- README.md
+- Rakefile
+- docs/architecture.md
+- docs/prd.md
+- docs/stories/1.1.story.md
+- docs/stories/1.2.story.md
+- docs/stories/1.3.story.md
+- docs/stories/1.4.story.md
+- docs/stories/1.5.story.md
+- docs/stories/1.6.story.md
+- docs/stories/2.1.story.md
+- examples/README.md
+- examples/batch_process.rb
+- examples/check_credits.rb
+- examples/process_receipt.rb
+- examples/quick_test.rb
+- lib/tabscanner.rb
+- lib/tabscanner/client.rb
+- lib/tabscanner/config.rb
+- lib/tabscanner/credits.rb
+- lib/tabscanner/errors/base_error.rb
+- lib/tabscanner/errors/configuration_error.rb
+- lib/tabscanner/errors/server_error.rb
+- lib/tabscanner/errors/unauthorized_error.rb
+- lib/tabscanner/errors/validation_error.rb
+- lib/tabscanner/http_client.rb
+- lib/tabscanner/request.rb
+- lib/tabscanner/result.rb
+- lib/tabscanner/version.rb
+- sig/tabscanner.rbs
+homepage: https://github.com/fkchang/tabscanner_ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/fkchang/tabscanner_ruby
+  source_code_uri: https://github.com/fkchang/tabscanner_ruby
+  changelog_uri: https://github.com/fkchang/tabscanner_ruby/blob/main/CHANGELOG.md
+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: Ruby gem for processing receipt images using the Tabscanner API
+test_files: []