hungrytable 0.0.8 → 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 03c04cacdda93b1d21d8a26fff6cc52759d2a69e3f8c37e15718c9c356ca5cc1
+  data.tar.gz: 5d90da3b15d1c81049375ee5d105cf0c50b58eab5d67562a1db50400d042e87a
+SHA512:
+  metadata.gz: 8bf655f9a26eab925b1e703a5b48d6cc43de861446106c63728a3000ed29a4665d2c118e542e1511c4f90fec47a7a5e14c54913a0be87d4eefaa12a15bebe56e
+  data.tar.gz: ebaa8f601e1959e7ae933e0d8cbf8d4ee559af9c94321990da1b9c17bdfb8b2a8f075203dc2efb7e8ce4272792fc9c4b75f19eed534e6febffc34cc072406517

data/README.md

@@ -1,54 +1,331 @@
 # Hungrytable
 
-The purpose of this gem is to interact with the [OpenTable](http://www.opentable.com) REST API.
+[![CI](https://github.com/dchapman1988/hungrytable/actions/workflows/ci.yml/badge.svg)](https://github.com/dchapman1988/hungrytable/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/dchapman1988/hungrytable/graph/badge.svg)](https://codecov.io/gh/dchapman1988/hungrytable)
+[![Ruby Version](https://img.shields.io/badge/ruby-3.0%2B-red.svg)](https://www.ruby-lang.org/)
+[![Gem Version](https://badge.fury.io/rb/hungrytable.svg)](https://badge.fury.io/rb/hungrytable)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Ruby client for the OpenTable REST API. Supports restaurant search, availability lookup, reservations, and booking management.
+
+## Features
+
+- Fetch restaurant details
+- Search available reservation times
+- Lock time slots before booking
+- Create and cancel reservations
+- Check reservation status
+- Requires Ruby 3.0+
+- No `method_missing` - all methods explicitly defined
+- Error classes for different failure types
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'hungrytable'
+```ruby
+gem 'hungrytable'
+```
 
 And then execute:
 
-    $ bundle
+```bash
+$ bundle install
+```
 
 Or install it yourself as:
 
-    $ gem install hungrytable
+```bash
+$ gem install hungrytable
+```
+
+## Configuration
+
+### Environment Variables
+
+Set the following environment variables (recommended for production):
+
+```bash
+export OT_PARTNER_ID=<YOUR OPENTABLE PARTNER ID>
+export OT_OAUTH_KEY=<YOUR OPENTABLE OAUTH KEY>
+export OT_OAUTH_SECRET=<YOUR OPENTABLE OAUTH SECRET KEY>
+```
+
+### Programmatic Configuration
+
+Alternatively, configure programmatically in your code:
+
+```ruby
+Hungrytable.configure do |config|
+  config.partner_id = 'your_partner_id'
+  config.oauth_key = 'your_oauth_key'
+  config.oauth_secret = 'your_oauth_secret'
+end
+```
 
 ## Usage
 
-You need to set some environment variable for this gem to work properly:
+### 1. Get Restaurant Details
+
+```ruby
+restaurant = Hungrytable::Restaurant.new(82591)
+
+if restaurant.valid?
+  puts restaurant.restaurant_name
+  puts restaurant.address
+  puts restaurant.phone
+  puts restaurant.primary_food_type
+  puts restaurant.price_range
+else
+  puts "Error: #{restaurant.error_message}"
+end
+```
+
+Available restaurant attributes:
+- `restaurant_name`, `restaurant_ID`
+- `address`, `city`, `state`, `postal_code`
+- `phone`, `url`
+- `latitude`, `longitude`
+- `neighborhood_name`, `metro_name`
+- `primary_food_type`, `price_range`
+- `restaurant_description`
+- `parking`, `parking_details`
+- `image_link`
+
+### 2. Search for Availability
+
+```ruby
+restaurant = Hungrytable::Restaurant.new(82591)
+
+# Search for a table for 4 people, 5 days from now at 7pm
+search_time = 5.days.from_now.change(hour: 19, min: 0)
+search = Hungrytable::RestaurantSearch.new(
+  restaurant,
+  date_time: search_time,
+  party_size: 4
+)
+
+if search.valid?
+  puts "Exact time: #{search.exact_time}" if search.exact_time
+  puts "Early time: #{search.early_time}" if search.early_time
+  puts "Later time: #{search.later_time}" if search.later_time
+  puts "Best time: #{search.ideal_time}"
+else
+  puts "No availability: #{search.error_message}"
+end
+```
+
+### 3. Lock a Time Slot
+
+```ruby
+slotlock = Hungrytable::RestaurantSlotlock.new(search)
+
+if slotlock.successful?
+  puts "Slot locked! ID: #{slotlock.slotlock_id}"
+else
+  puts "Failed to lock slot: #{slotlock.errors}"
+end
+```
+
+### 4. Make a Reservation
+
+```ruby
+reservation = Hungrytable::ReservationMake.new(
+  slotlock,
+  email_address: 'john.doe@example.com',
+  firstname: 'John',
+  lastname: 'Doe',
+  phone: '5551234567',
+  specialinstructions: 'Window seat please'
+)
+
+if reservation.successful?
+  puts "Reservation confirmed! Number: #{reservation.confirmation_number}"
+else
+  puts "Reservation failed: #{reservation.error_message}"
+end
+```
+
+### 5. Check Reservation Status
+
+```ruby
+status = Hungrytable::ReservationStatus.new(
+  restaurant_id: 82591,
+  confirmation_number: 'ABC123XYZ'
+)
+
+if status.successful?
+  puts "Status: #{status.status}"
+  details = status.reservation_details
+  puts "Restaurant: #{details[:restaurant_name]}"
+  puts "Date/Time: #{details[:date_time]}"
+  puts "Party Size: #{details[:party_size]}"
+end
+```
+
+### 6. Cancel a Reservation
+
+```ruby
+cancel = Hungrytable::ReservationCancel.new(
+  email_address: 'john.doe@example.com',
+  confirmation_number: 'ABC123XYZ',
+  restaurant_id: 82591
+)
 
-Observe:
+if cancel.successful?
+  puts "Reservation cancelled successfully"
+else
+  puts "Cancellation failed: #{cancel.error_message}"
+end
+```
 
-    # In ~/.bashrc
-    export OT_PARTNER_ID=<YOUR OPENTABLE PARTNER ID>
-    export OT_PARTNER_AUTH=<YOUR OPENTABLE PARTNER AUTH> # For XML feed only...
-    export OT_OAUTH_KEY=<YOUR OPENTABLE OAUTH KEY>
-    export OT_OAUTH_SECRET=<YOUR OPENTABLE OAUTH SECRET KEY>
+### Complete Example: Full Reservation Flow
 
-## Example Run
+```ruby
+require 'hungrytable'
 
-    $ restaurant = Hungrytable::Restaurant.new(82591)  
+# Configure
+Hungrytable.configure do |config|
+  config.partner_id = ENV['OT_PARTNER_ID']
+  config.oauth_key = ENV['OT_OAUTH_KEY']
+  config.oauth_secret = ENV['OT_OAUTH_SECRET']
+end
 
-    > #<Hungrytable::Restaurant:0x0000000032e4098 ... >  
+# 1. Get restaurant details
+restaurant = Hungrytable::Restaurant.new(82591)
+raise "Restaurant not found" unless restaurant.valid?
 
-    $ search = Hungrytable::RestaurantSearch.new(restaurant, {date_time: 5.days.from_now, party_size: 3})  
+puts "Booking at: #{restaurant.restaurant_name}"
 
-    > #<Hungrytable::RestaurantSearch:0x00000003143388 ... >
+# 2. Search for availability
+search_time = 3.days.from_now.change(hour: 19, min: 0)
+search = Hungrytable::RestaurantSearch.new(
+  restaurant,
+  date_time: search_time,
+  party_size: 2
+)
 
-    $ slotlock = Hungrytable::RestaurantSlotlock.new(search)
+raise "No availability" unless search.valid?
 
-    > #<Hungrytable::RestaurantSlotlock:0x00000002973a68 ... >
+puts "Found time slot: #{search.ideal_time}"
 
-    $ reservation = Hungrytable::ReservationMake.new(slotlock, {email_address: 'foo@bar.com', firstname: 'Mike', lastname: 'Jones', phone: '2813308004'})
+# 3. Lock the slot
+slotlock = Hungrytable::RestaurantSlotlock.new(search)
+raise "Could not lock slot: #{slotlock.errors}" unless slotlock.successful?
+
+# 4. Make the reservation
+reservation = Hungrytable::ReservationMake.new(
+  slotlock,
+  email_address: 'diner@example.com',
+  firstname: 'Jane',
+  lastname: 'Smith',
+  phone: '5551234567'
+)
+
+if reservation.successful?
+  puts "Success! Confirmation: #{reservation.confirmation_number}"
+else
+  puts "Failed: #{reservation.error_message}"
+end
+```
+
+## Error Handling
+
+Available error classes:
+
+```ruby
+begin
+  restaurant = Hungrytable::Restaurant.new(invalid_id)
+rescue Hungrytable::ConfigurationError => e
+  puts "Configuration error: #{e.message}"
+rescue Hungrytable::HTTPError => e
+  puts "HTTP error: #{e.message}"
+rescue Hungrytable::APIError => e
+  puts "API error #{e.error_code}: #{e.error_message}"
+rescue Hungrytable::MissingRequiredFieldError => e
+  puts "Missing required field: #{e.message}"
+end
+```
+
+Error hierarchy:
+- `Hungrytable::Error` (base class)
+  - `ConfigurationError` - Missing or invalid configuration
+  - `HTTPError` - HTTP-level errors
+    - `NotFoundError` - 404 errors
+    - `UnauthorizedError` - 401 authentication errors
+    - `ServerError` - 5xx server errors
+  - `APIError` - OpenTable API errors
+  - `ValidationError` - Input validation errors
+    - `MissingRequiredFieldError` - Missing required parameters
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `rake test` to run the tests.
+
+### Running Tests
+
+```bash
+bundle exec rake test
+```
+
+### Running RuboCop
+
+```bash
+bundle exec rubocop
+```
+
+### Auto-fixing RuboCop Issues
+
+```bash
+bundle exec rubocop -A
+```
+
+## Requirements
+
+- Ruby >= 3.0.0
+- OpenTable Partner API credentials
+
+## Dependencies
+
+Runtime:
+- `activesupport` (>= 6.0)
+- `http` (~> 5.0)
+- `oauth` (~> 1.1)
+
+Development:
+- `minitest` (~> 5.20) - Testing framework
+- `webmock` (~> 3.20) - HTTP mocking for tests
+- `rubocop` (~> 1.60) - Code quality and style
+- `mocha` (~> 2.1) - Mocking and stubbing
 
 
 ## Contributing
 
-1. Fork it
+1. Fork it (https://github.com/dchapman1988/hungrytable/fork)
 2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Added some feature'`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+5. Create a new Pull Request
+
+Please ensure:
+- All tests pass (`bundle exec rake test`)
+- RuboCop is clean (`bundle exec rubocop`)
+- New features have tests
+- Code follows existing style
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE).
+
+## Maintainers
+
+**Active:**
+- David Chapman ([@dchapman1988](https://github.com/dchapman1988))
+
+**Inactive:**
+- Nicholas Fine ([@yrgoldteeth](https://github.com/yrgoldteeth))
+- Ryan T. Hosford ([@rthbound](https://github.com/rthbound))
+
+## Changelog
+
+See [RELEASE_NOTES.md](RELEASE_NOTES.md) for version history.

data/RELEASE_NOTES.md

@@ -1,5 +1,21 @@
 # Hungrytable - Ruby API Client for the OpenTable REST API
 
+## v1.0.0 (2025-01-XX)
+
+### Breaking Changes
+- Requires Ruby 3.0+
+- Replaced `curb` with `http` gem
+- Replaced `method_missing` with explicit method definitions
+
+### Changes
+- Fixed deprecated `URI.encode`/`URI.decode` → `CGI.escape`/`CGI.unescape`
+- Added `oauth` gem for OAuth 1.0
+- RuboCop clean, Ruby 3.0+ code style
+- Added 152 tests
+- Added GitHub Actions CI
+
+---
+
 ## v0.0.1 (05/11/2012)
 
 * Get relevant details about an individual restaurant.

data/lib/hungrytable/api_health_monitor.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Hungrytable
+  # Monitors API health and detects potential deprecation or degradation
+  class ApiHealthMonitor
+    class << self
+      # Check if API is healthy
+      # @return [Hash] health status
+      def health_check
+        {
+          timestamp: Time.now.utc.iso8601,
+          status: check_status,
+          circuit_breaker: CircuitBreaker.stats,
+          endpoint: Config.base_url,
+          warnings: warnings
+        }
+      end
+
+      # Perform a lightweight health check
+      # @return [Symbol] :healthy, :degraded, or :down
+      def check_status
+        return :down if CircuitBreaker.open?
+
+        begin
+          # Try a simple request
+          restaurant = Restaurant.new(82591)
+          restaurant.valid? ? :healthy : :degraded
+        rescue UnauthorizedError
+          :unauthorized
+        rescue ServerError, HTTPError
+          :down
+        rescue StandardError
+          :unknown
+        end
+      end
+
+      # Get warnings about potential issues
+      # @return [Array<Hash>] warnings
+      def warnings
+        warnings = []
+
+        if CircuitBreaker.open?
+          warnings << {
+            level: :critical,
+            message: 'Circuit breaker is OPEN - API appears to be down',
+            action: 'Wait for circuit breaker timeout or contact OpenTable support'
+          }
+        end
+
+        if check_oauth_version_deprecated?
+          warnings << {
+            level: :warning,
+            message: 'Using OAuth 1.0 which may be deprecated',
+            action: 'Consider migrating to modern OpenTable API (OAuth 2.0)'
+          }
+        end
+
+        if check_legacy_endpoint?
+          warnings << {
+            level: :warning,
+            message: 'Using legacy otapi_v3.ashx endpoint (2012 vintage)',
+            action: 'Verify endpoint is still supported with OpenTable'
+          }
+        end
+
+        warnings
+      end
+
+      # Log API health to stdout or logger
+      # @param logger [Logger] optional logger
+      def log_health(logger = nil)
+        health = health_check
+        output = logger || $stdout
+
+        case health[:status]
+        when :healthy
+          output.puts "[Hungrytable] API Status: HEALTHY"
+        when :degraded
+          output.puts "[Hungrytable] API Status: DEGRADED - Some endpoints may be failing"
+        when :down
+          output.puts "[Hungrytable] API Status: DOWN - API is not responding"
+        when :unauthorized
+          output.puts "[Hungrytable] API Status: UNAUTHORIZED - Check credentials"
+        else
+          output.puts "[Hungrytable] API Status: UNKNOWN"
+        end
+
+        health[:warnings].each do |warning|
+          output.puts "[Hungrytable] [#{warning[:level].to_s.upcase}] #{warning[:message]}"
+        end
+      end
+
+      private
+
+      def check_oauth_version_deprecated?
+        # OAuth 1.0 is considered legacy
+        true
+      end
+
+      def check_legacy_endpoint?
+        # otapi_v3.ashx is from 2012
+        Config.base_url.include?('otapi_v3.ashx')
+      end
+    end
+  end
+end

data/lib/hungrytable/circuit_breaker.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Hungrytable
+  # Circuit Breaker pattern to prevent cascading failures when API is down
+  #
+  # States:
+  # - CLOSED: Normal operation, requests pass through
+  # - OPEN: Too many failures, requests fail immediately
+  # - HALF_OPEN: Testing if service recovered
+  #
+  # Usage:
+  #   Hungrytable::CircuitBreaker.call do
+  #     # Make API request
+  #   end
+  class CircuitBreaker
+    class CircuitOpenError < Error
+      def initialize(message = nil)
+        super(message || 'Circuit breaker is OPEN. API appears to be down. Try again later.')
+      end
+    end
+
+    class << self
+      # Execute a block with circuit breaker protection
+      # @yield Block to execute
+      # @raise [CircuitOpenError] if circuit is open
+      # @return Result of the block
+      def call(&block)
+        instance.call(&block)
+      end
+
+      # Check if circuit is open
+      # @return [Boolean]
+      def open?
+        instance.open?
+      end
+
+      # Get current state
+      # @return [Symbol] :closed, :open, or :half_open
+      def state
+        instance.state
+      end
+
+      # Get circuit breaker statistics
+      # @return [Hash] statistics
+      def stats
+        instance.stats
+      end
+
+      # Reset the circuit breaker
+      def reset!
+        instance.reset!
+      end
+
+      # Configure circuit breaker
+      # @param failure_threshold [Integer] Number of failures before opening
+      # @param timeout [Integer] Seconds to wait before entering half-open state
+      # @param success_threshold [Integer] Successes needed in half-open to close
+      def configure(failure_threshold: 5, timeout: 60, success_threshold: 2)
+        instance.configure(
+          failure_threshold: failure_threshold,
+          timeout: timeout,
+          success_threshold: success_threshold
+        )
+      end
+
+      private
+
+      def instance
+        @instance ||= new
+      end
+    end
+
+    attr_reader :state, :failure_count, :success_count, :last_failure_time
+
+    def initialize
+      @state = :closed
+      @failure_count = 0
+      @success_count = 0
+      @last_failure_time = nil
+      @mutex = Mutex.new
+
+      # Default configuration
+      @config = {
+        failure_threshold: 5,     # Open after 5 failures
+        timeout: 60,              # Try again after 60 seconds
+        success_threshold: 2      # Close after 2 successes in half-open
+      }
+    end
+
+    def configure(failure_threshold: nil, timeout: nil, success_threshold: nil)
+      @mutex.synchronize do
+        @config[:failure_threshold] = failure_threshold if failure_threshold
+        @config[:timeout] = timeout if timeout
+        @config[:success_threshold] = success_threshold if success_threshold
+      end
+    end
+
+    def call
+      @mutex.synchronize do
+        check_state_transition
+
+        if @state == :open
+          raise CircuitOpenError
+        end
+      end
+
+      begin
+        result = yield
+        record_success
+        result
+      rescue UnauthorizedError, ServerError, HTTPError => e
+        record_failure
+        raise e
+      end
+    end
+
+    def open?
+      @state == :open
+    end
+
+    def stats
+      {
+        state: @state,
+        failure_count: @failure_count,
+        success_count: @success_count,
+        last_failure_time: @last_failure_time,
+        config: @config
+      }
+    end
+
+    def reset!
+      @mutex.synchronize do
+        @state = :closed
+        @failure_count = 0
+        @success_count = 0
+        @last_failure_time = nil
+      end
+    end
+
+    private
+
+    def check_state_transition
+      return unless @state == :open
+
+      if Time.now - @last_failure_time >= @config[:timeout]
+        @state = :half_open
+        @success_count = 0
+      end
+    end
+
+    def record_success
+      @mutex.synchronize do
+        @failure_count = 0
+
+        if @state == :half_open
+          @success_count += 1
+          if @success_count >= @config[:success_threshold]
+            @state = :closed
+            @success_count = 0
+          end
+        end
+      end
+    end
+
+    def record_failure
+      @mutex.synchronize do
+        @failure_count += 1
+        @last_failure_time = Time.now
+        @success_count = 0
+
+        if @failure_count >= @config[:failure_threshold]
+          @state = :open
+        end
+      end
+    end
+  end
+end