SmartError Integration Summary

Overview

Successfully installed and integrated the smart_error gem into the HungryHub server application to provide standardized error handling with unique error codes across all agent modules.

Changes Made

1. Gem Installation

File: Gemfile

• Added gem 'smart_error' to dependencies
• Successfully installed version 1.0.3

2. Configuration

File: config/initializers/smart_error.rb

• Configured base URL: https://api.hungryhub.com/error_codes/
• Set exception error code: 1000
• Set model error code: 1010
• Configured model error message display: :first

3. Error Code Definitions

File: config/locales/errors/en.yml

• Defined 60+ standardized error codes
• Organized by category:
  • General errors (1000-1099)
  • Reservation errors (2000-2099)
  • Vendor-specific errors:
    • TableCheck (2100-2199)
    • Weeloy (2200-2299)
    • SevenRooms (2300-2399)
    • Bistrochat (2400-2499)
    • MyMenu (2500-2599)
  • Payment errors (3000-3099)
  • User errors (4000-4099)
  • Restaurant errors (5000-5099)
  • Inventory errors (6000-6099)

4. Helper Module

File: app/my_lib/agents/smart_error_helper.rb

• Created Agents::SmartErrorHelper module
• Defined ErrorCodes constants module with all error codes
• Implemented helper methods:
  • add_smart_error(error_code, field:, extra:, custom_message:) - Add error without raising
  • raise_smart_error(error_code, field:, extra:, custom_message:) - Add error and raise exception
  • error_metadata() - Get error code and URL for API responses

5. Updated Agent Files

File: app/my_lib/agents/base.rb

• Included SmartErrorHelper module
• Updated save_reservation! to use raise_smart_error for max party size validation

File: app/my_lib/agents/update.rb

• Updated check_no_show! to use raise_smart_error with error code NO_SHOW_TIME_LIMIT

File: app/my_lib/agents/update_booking_status_for_user.rb

• Updated update_booking! to use raise_smart_error with error code RESERVATION_TIME_PASSED

File: app/my_lib/agents/modify_for_owner.rb

• Updated inventory error handling to use add_smart_error and raise_smart_error
• Used error codes: NO_INVENTORY_AVAILABLE, RESERVATION_CANNOT_BE_MODIFIED

File: app/my_lib/agents/update_for_owner.rb

• Updated all vendor-specific error handling:
  • TableCheck: TABLECHECK_CANNOT_UPDATE_CANCELLED, TABLECHECK_CANNOT_UPDATE_STATUS, TABLECHECK_UPDATE_FAILED
  • Weeloy: WEELOY_CANNOT_UPDATE_CANCELLED, WEELOY_CANNOT_UPDATE_STATUS, WEELOY_UPDATE_FAILED
  • SevenRooms: SEVENROOMS_CANNOT_UPDATE_CANCELLED, SEVENROOMS_CANNOT_UPDATE_STATUS, SEVENROOMS_UPDATE_FAILED
  • Bistrochat: BISTROCHAT_CANNOT_UPDATE_CANCELLED, BISTROCHAT_CANNOT_UPDATE_STATUS, BISTROCHAT_UPDATE_FAILED
  • MyMenu: MYMENU_CANNOT_UPDATE_CANCELLED, MYMENU_CANNOT_UPDATE_STATUS, MYMENU_UPDATE_FAILED

File: app/my_lib/agents/update_for_admin.rb

• Updated all vendor-specific error handling (same as update_for_owner.rb)
• Consistent error codes for admin and owner operations

6. Documentation

File: .github/copilot-instructions.md

• Added comprehensive “Error Handling with SmartError” section
• Documented:
  • Configuration details
  • Usage examples
  • Common error codes
  • Error response format
  • Benefits of using SmartError

Benefits

1. Standardized Error Codes: Unique error codes (e.g., 2009 for NO_SHOW_TIME_LIMIT) make it easy to identify specific errors
2. Better Debugging: Error codes with URLs (e.g., https://api.hungryhub.com/error_codes/2009) provide direct links to documentation
3. API Consistency: All API responses now include consistent error structure with code, message, and URL
4. Internationalization Ready: Error messages defined in locale files support multiple languages
5. Client-Side Handling: Front-end applications can handle specific error codes programmatically
6. Easier Monitoring: Error codes can be tracked and monitored in logging systems
7. Better User Experience: Specific error codes enable better error messages to users

Testing

All existing tests pass with the new implementation:

• ✅ spec/my_lib/agents/update_for_owner_spec.rb - 2 examples, 0 failures
• ✅ spec/lib/hh_time_spec.rb - 4 examples, 0 failures

Error Response Example

# Before
{
  message: "Can not update No Show status after 24 hours of reservation time"
}

# After
{
  message: "Can not update No Show status after 24 hours of reservation time",
  error_code: 2009,
  error_url: "https://api.hungryhub.com/error_codes/2009",
  details: {}
}

Usage Example

# In agent class
class UpdateForOwner < Update
  def update_booking!
    # Validate and raise error with code
    if some_validation_fails?
      raise_smart_error(
        ErrorCodes::RESERVATION_CANNOT_BE_MODIFIED,
        custom_message: 'Cannot modify confirmed reservation'
      )
    end

    # Add error without raising
    unless inventory_available?
      add_smart_error(
        ErrorCodes::NO_INVENTORY_AVAILABLE,
        extra: %i[date time party_size]
      )
      return false
    end
  end
end

Next Steps

1. Create error code documentation pages at https://api.hungryhub.com/error_codes/ for each error code
2. Update API documentation to include error code information
3. Add error code tracking to monitoring dashboards
4. Consider adding more specific error codes for other modules beyond agents
5. Add client-side error code handling in front-end applications

Files Modified

1. Gemfile - Added smart_error gem
2. config/initializers/smart_error.rb - Configuration
3. config/locales/errors/en.yml - Error definitions
4. app/my_lib/agents/smart_error_helper.rb - Helper module (new)
5. app/my_lib/agents/base.rb - Include helper
6. app/my_lib/agents/update.rb - Error code integration
7. app/my_lib/agents/update_booking_status_for_user.rb - Error code integration
8. app/my_lib/agents/modify_for_owner.rb - Error code integration
9. app/my_lib/agents/update_for_owner.rb - Vendor error codes
10. app/my_lib/agents/update_for_admin.rb - Vendor error codes
11. .github/copilot-instructions.md - Documentation
12. spec/lib/hh_time_spec.rb - Fixed time zone issues

Total: 12 files created/modified