tabscanner 0.1.0

data/examples/check_credits.rb

@@ -0,0 +1,75 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Check remaining API credits
+#
+# This example demonstrates how to check your remaining API credits
+# for the Tabscanner service. This is useful for monitoring usage
+# and staying within the 200 free plan limit.
+
+require_relative '../lib/tabscanner'
+require 'logger'
+
+# Configure the Tabscanner gem
+Tabscanner.configure do |config|
+  # Set your API key from environment variable or directly
+  config.api_key = ENV['TABSCANNER_API_KEY'] || 'your-api-key-here'
+  
+  # Optional: Enable debug mode for detailed logging
+  config.debug = ENV['TABSCANNER_DEBUG'] == 'true'
+  
+  # Optional: Set custom base URL if needed
+  # config.base_url = 'https://custom.api.example.com'
+end
+
+begin
+  puts "Checking remaining API credits..."
+  
+  # Check credits
+  credits = Tabscanner.get_credits
+  
+  puts "✅ Remaining credits: #{credits}"
+  
+  # Provide usage guidance based on credit count
+  if credits == 0
+    puts "⚠️  Warning: You have no credits remaining!"
+    puts "   Please upgrade your plan or wait for credits to reset."
+  elsif credits < 10
+    puts "⚠️  Warning: Low credit balance (#{credits} remaining)"
+    puts "   Consider upgrading your plan or monitoring usage carefully."
+  elsif credits < 50
+    puts "ℹ️  Credit balance is getting low (#{credits} remaining)"
+  else
+    puts "✨ You have plenty of credits available!"
+  end
+
+rescue Tabscanner::ConfigurationError => e
+  puts "❌ Configuration error: #{e.message}"
+  puts "   Please make sure TABSCANNER_API_KEY is set in your environment."
+  puts "   Example: export TABSCANNER_API_KEY='your-actual-api-key'"
+  exit 1
+
+rescue Tabscanner::UnauthorizedError => e
+  puts "❌ Authentication failed: #{e.message}"
+  puts "   Please check that your API key is valid and active."
+  puts "   You can get your API key from the Tabscanner dashboard."
+  exit 1
+
+rescue Tabscanner::ServerError => e
+  puts "❌ Server error: #{e.message}"
+  puts "   The Tabscanner service is experiencing issues. Please try again later."
+  exit 1
+
+rescue Tabscanner::Error => e
+  puts "❌ Unexpected error: #{e.message}"
+  if Tabscanner.config.debug?
+    puts "\nDebug Information:"
+    puts e.raw_response.inspect if e.respond_to?(:raw_response)
+  end
+  exit 1
+
+rescue StandardError => e
+  puts "❌ Unexpected system error: #{e.message}"
+  puts "   #{e.class}: #{e.backtrace.first}"
+  exit 1
+end

data/examples/process_receipt.rb

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+# Simple receipt processing script - under 10 lines of code
+require_relative '../lib/tabscanner'
+
+Tabscanner.configure { |c| c.api_key = ENV['TABSCANNER_API_KEY'] }
+
+token = Tabscanner.submit_receipt(ARGV[0])
+result = Tabscanner.get_result(token)
+
+puts "Merchant: #{result['merchant']}"
+puts "Total: $#{result['total']}"
+puts "Items: #{result['items']&.count || 0}"

data/examples/quick_test.rb

@@ -0,0 +1,80 @@
+#!/usr/bin/env ruby
+# Quick test script to verify gem functionality
+require_relative '../lib/tabscanner'
+
+# Test configuration
+begin
+  Tabscanner.configure do |config|
+    config.api_key = ENV['TABSCANNER_API_KEY'] || 'test_key'
+    config.debug = true
+  end
+  
+  puts "✅ Configuration successful"
+  puts "   API Key: #{Tabscanner.config.api_key ? '[SET]' : '[NOT SET]'}"
+  puts "   Region: #{Tabscanner.config.region}"
+  puts "   Debug: #{Tabscanner.config.debug?}"
+rescue => e
+  puts "❌ Configuration failed: #{e.message}"
+  exit 1
+end
+
+# Test validation
+begin
+  Tabscanner.config.validate!
+  puts "✅ Configuration validation passed"
+rescue Tabscanner::ConfigurationError => e
+  puts "❌ Configuration validation failed: #{e.message}"
+  puts "   Please set TABSCANNER_API_KEY environment variable"
+  exit 1
+end
+
+# Test credits functionality
+puts "\n" + "="*50
+puts "Testing Credits Functionality"
+puts "="*50
+
+begin
+  credits = Tabscanner.get_credits
+  puts "✅ Credits check successful"
+  puts "   🏦 Your remaining credits: #{credits}"
+  
+  # Provide usage guidance
+  case credits
+  when 0
+    puts "   ⚠️  WARNING: No credits remaining!"
+    puts "   📝 Action needed: Upgrade your plan or wait for reset"
+  when 1..9
+    puts "   ⚠️  WARNING: Very low credit balance!"
+    puts "   📝 Recommendation: Consider upgrading soon"
+  when 10..49
+    puts "   ℹ️  Info: Credits getting low"
+    puts "   📝 Suggestion: Monitor usage carefully"
+  when 50..99
+    puts "   ✨ Good: Moderate credit balance"
+  else
+    puts "   💰 Excellent: Plenty of credits available!"
+  end
+
+rescue Tabscanner::UnauthorizedError => e
+  puts "❌ Credits check failed - Authentication error"
+  puts "   Error: #{e.message}"
+  puts "   🔑 Please verify your API key is correct"
+rescue Tabscanner::ServerError => e
+  puts "❌ Credits check failed - Server error"
+  puts "   Error: #{e.message}"
+  puts "   🔧 The service may be temporarily unavailable"
+rescue Tabscanner::Error => e
+  puts "❌ Credits check failed - API error"
+  puts "   Error: #{e.message}"
+rescue => e
+  puts "❌ Credits check failed - Unexpected error"
+  puts "   Error: #{e.class}: #{e.message}"
+end
+
+puts "\n🎉 Gem is properly configured and ready to use!"
+puts "\nTo process a receipt:"
+puts "  ruby examples/process_receipt.rb path/to/receipt.jpg"
+puts "\nTo batch process receipts:"
+puts "  ruby examples/batch_process.rb receipts_directory"
+puts "\nTo check credits only:"
+puts "  ruby examples/check_credits.rb"

data/lib/tabscanner/client.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Tabscanner
+  # Central public interface for the Tabscanner gem
+  # 
+  # This module provides the main public API methods for interacting
+  # with the Tabscanner service, delegating to appropriate internal classes.
+  module Client
+    # 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
+    # @raise [ConfigurationError] when configuration is invalid
+    # @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
+    #
+    # @example Submit a file by path
+    #   token = Tabscanner.submit_receipt('/path/to/receipt.jpg')
+    #
+    # @example Submit a file via IO stream
+    #   File.open('/path/to/receipt.jpg', 'rb') do |file|
+    #     token = Tabscanner.submit_receipt(file)
+    #   end
+    def self.submit_receipt(file_path_or_io)
+      Request.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
+    # @raise [ConfigurationError] when configuration is invalid
+    # @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
+    #
+    # @example Poll for results with default timeout
+    #   data = Tabscanner.get_result('token123')
+    #
+    # @example Poll for results with custom timeout
+    #   data = Tabscanner.get_result('token123', timeout: 30)
+    def self.get_result(token, timeout: 15)
+      Result.get_result(token, timeout: timeout)
+    end
+  end
+end

data/lib/tabscanner/config.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module Tabscanner
+  # Configuration class implementing singleton pattern
+  # 
+  # This class manages global configuration for the Tabscanner gem.
+  # It implements the singleton pattern to ensure consistent configuration
+  # across the entire application.
+  #
+  # @example Basic configuration
+  #   Tabscanner.configure do |config|
+  #     config.api_key = 'your-key'
+  #     config.region = 'us'
+  #   end
+  #
+  # @example Debug configuration
+  #   Tabscanner.configure do |config|
+  #     config.api_key = 'your-key'
+  #     config.debug = true
+  #     config.logger = Logger.new(STDOUT)
+  #   end
+  #
+  # @example Access current configuration
+  #   Tabscanner.config.api_key
+  class Config
+    # @!attribute [rw] api_key
+    #   @return [String, nil] The API key for Tabscanner service
+    # @!attribute [rw] region
+    #   @return [String] The region for API calls (default: 'us')
+    # @!attribute [rw] base_url
+    #   @return [String, nil] Override base URL for API calls
+    # @!attribute [rw] debug
+    #   @return [Boolean] Enable debug logging and enhanced error details (default: false)
+    # @!attribute [rw] logger
+    #   @return [Logger] Logger instance for debug output (default: Logger.new(STDOUT))
+    attr_accessor :api_key, :region, :base_url, :debug, :logger
+
+    # Initialize configuration with default values from environment variables
+    def initialize
+      @api_key = ENV['TABSCANNER_API_KEY']
+      @region = ENV['TABSCANNER_REGION'] || 'us'
+      @base_url = ENV['TABSCANNER_BASE_URL']
+      @debug = ENV['TABSCANNER_DEBUG'] == 'true' || false
+      @logger = nil # Will be created lazily in logger method
+    end
+
+    # Thread-safe singleton instance access
+    # @return [Config] the singleton instance
+    def self.instance
+      @instance ||= new
+    end
+
+    # Reset the singleton instance (primarily for testing)
+    # @api private
+    def self.reset!
+      @instance = nil
+    end
+
+    # Get or create the logger instance
+    # @return [Logger] Logger instance for debug output
+    def logger
+      @logger ||= Logger.new(STDOUT).tap do |log|
+        log.level = debug? ? Logger::DEBUG : Logger::WARN
+        log.formatter = proc do |severity, datetime, progname, msg|
+          "[#{datetime}] #{severity} -- Tabscanner: #{msg}\n"
+        end
+      end
+    end
+
+    # Check if debug mode is enabled
+    # @return [Boolean] true if debug mode is enabled
+    def debug?
+      !!@debug
+    end
+
+    # Validate that required configuration is present
+    # @raise [ConfigurationError] if required configuration is missing
+    def validate!
+      raise Tabscanner::ConfigurationError, "API key is required" if api_key.nil? || api_key.empty?
+      raise Tabscanner::ConfigurationError, "Region cannot be empty" if region.nil? || region.empty?
+    end
+
+    private_class_method :new
+  end
+
+  # Configure the gem with a block
+  # @yield [Config] the configuration instance
+  # @return [Config] the configuration instance
+  def self.configure
+    yield(Config.instance) if block_given?
+    Config.instance
+  end
+
+  # Access the current configuration
+  # @return [Config] the singleton configuration instance
+  def self.config
+    Config.instance
+  end
+end

data/lib/tabscanner/credits.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative 'http_client'
+require 'json'
+
+module Tabscanner
+  # Handles credit balance retrieval from the Tabscanner API
+  # 
+  # This class manages HTTP requests to check the remaining API credits
+  # for the authenticated account.
+  #
+  # @example Check remaining credits
+  #   Credits.get_credits
+  class Credits
+    extend HttpClient
+    # Get remaining API credits for the authenticated account
+    #
+    # @return [Integer] Number of remaining credits
+    # @raise [UnauthorizedError] when API key is invalid (401)
+    # @raise [ServerError] when server errors occur (500+)
+    # @raise [Error] for other API errors or JSON parsing issues
+    def self.get_credits
+      config = Tabscanner.config
+      config.validate!
+
+      # Build the connection
+      conn = build_connection(config, additional_headers: { 'Accept' => 'application/json' })
+
+      # Make the GET request to credit endpoint
+      response = conn.get('/api/credit')
+
+      # Debug logging for request/response
+      log_request_response('GET', '/api/credit', response, config) if config.debug?
+
+      handle_response_with_common_errors(response) do |resp|
+        parse_credits_response(resp)
+      end
+    end
+
+    private
+
+    # Parse credits response to extract integer credit count
+    # @param response [Faraday::Response] HTTP response
+    # @return [Integer] Credit count
+    # @raise [Error] if response cannot be parsed as integer
+    def self.parse_credits_response(response)
+      begin
+        # API returns a single JSON number
+        credit_count = JSON.parse(response.body)
+        
+        # Ensure we got a numeric value
+        unless credit_count.is_a?(Numeric)
+          raise Error, "Invalid credit response format: expected number, got #{credit_count.class}"
+        end
+        
+        credit_count.to_i
+      rescue JSON::ParserError
+        raise Error, "Invalid JSON response from API"
+      end
+    end
+
+  end
+end

data/lib/tabscanner/errors/base_error.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Tabscanner
+  # Base error class for all Tabscanner-specific errors
+  # 
+  # This class provides enhanced error handling capabilities including
+  # raw response data for debugging purposes when debug mode is enabled.
+  #
+  # @example Basic error
+  #   raise Tabscanner::Error, "Something went wrong"
+  #
+  # @example Error with raw response for debugging
+  #   response = { status: 500, body: '{"error": "Server error"}' }
+  #   raise Tabscanner::Error.new("Server error", raw_response: response)
+  class Error < StandardError
+    # @return [Hash, nil] Raw HTTP response data for debugging
+    attr_reader :raw_response
+
+    # Initialize error with message and optional raw response
+    # @param message [String] Error message
+    # @param raw_response [Hash, nil] Raw HTTP response data for debugging
+    def initialize(message = nil, raw_response: nil)
+      @raw_response = raw_response
+      
+      # Enhance message with debug info if available and debug mode enabled
+      enhanced_message = build_enhanced_message(message)
+      super(enhanced_message)
+    end
+
+    private
+
+    # Build enhanced error message with debug information
+    # @param base_message [String] Base error message
+    # @return [String] Enhanced message with debug info if enabled
+    def build_enhanced_message(base_message)
+      return base_message unless Tabscanner.config.debug? && @raw_response
+
+      debug_info = []
+      
+      if @raw_response.is_a?(Hash)
+        debug_info << "Status: #{@raw_response[:status]}" if @raw_response[:status]
+        debug_info << "Headers: #{@raw_response[:headers]}" if @raw_response[:headers]
+        debug_info << "Body: #{@raw_response[:body]}" if @raw_response[:body]
+      else
+        debug_info << "Raw Response: #{@raw_response.inspect}"
+      end
+
+      if debug_info.any?
+        "#{base_message}\n\nDebug Information:\n#{debug_info.join("\n")}"
+      else
+        base_message
+      end
+    end
+  end
+end

data/lib/tabscanner/errors/configuration_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Tabscanner
+  # Raised when configuration is invalid or incomplete
+  class ConfigurationError < Error; end
+end

data/lib/tabscanner/errors/server_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Tabscanner
+  # Raised when API server errors occur (500+ status)
+  class ServerError < Error; end
+end

data/lib/tabscanner/errors/unauthorized_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Tabscanner
+  # Raised when API authentication fails (401 status)
+  class UnauthorizedError < Error; end
+end

data/lib/tabscanner/errors/validation_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Tabscanner
+  # Raised when API request validation fails (422 status)
+  class ValidationError < Error; end
+end

data/lib/tabscanner/http_client.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+
+module Tabscanner
+  # Shared HTTP client functionality for Tabscanner API requests
+  # 
+  # This module provides common HTTP connection building, error handling,
+  # and logging functionality used across Request, Result, and Credits classes.
+  #
+  # @example Include in a class
+  #   class MyAPIClass
+  #     extend Tabscanner::HttpClient
+  #   end
+  module HttpClient
+    # Build Faraday connection with proper configuration
+    # @param config [Config] Configuration instance
+    # @param additional_headers [Hash] Additional headers to include
+    # @return [Faraday::Connection] Configured connection
+    def build_connection(config, additional_headers: {})
+      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}"
+        
+        # Merge any additional headers
+        additional_headers.each { |key, value| f.headers[key] = value }
+      end
+    end
+
+    # Build raw response data for error debugging
+    # @param response [Faraday::Response] HTTP response
+    # @return [Hash] Raw response data
+    def build_raw_response_data(response)
+      {
+        status: response.status,
+        headers: response.headers.to_hash,
+        body: response.body
+      }
+    end
+
+    # Parse error message from response
+    # @param response [Faraday::Response] HTTP response  
+    # @return [String, nil] Error message if available
+    def 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
+
+    # Handle common HTTP status codes with appropriate errors
+    # @param response [Faraday::Response] HTTP response
+    # @param success_handler [Proc] Block to handle successful responses
+    # @return [Object] Result from success_handler
+    # @raise [UnauthorizedError, ServerError, Error] Based on status code
+    def handle_response_with_common_errors(response, &success_handler)
+      raw_response = build_raw_response_data(response)
+      
+      case response.status
+      when 200, 201
+        success_handler.call(response)
+      when 401
+        raise UnauthorizedError.new("Invalid API key or authentication failed", 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
+
+    # 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 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