liteapi 0.1.0

data/lib/liteapi/analytics.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Liteapi
+  module Analytics
+    # Retrieve weekly analytics
+    #
+    # Fetches weekly analytics data for a date range.
+    #
+    # @param from [String] Start date (YYYY-MM-DD)
+    # @param to [String] End date (YYYY-MM-DD)
+    # @return [Hash] Weekly analytics data
+    def weekly_analytics(from:, to:)
+      dashboard_post('analytics/weekly', { from: from, to: to })
+    end
+
+    # Retrieve detailed analytics report
+    #
+    # Fetches a detailed analytics report including revenue and sales data.
+    #
+    # @param from [String] Start date (YYYY-MM-DD)
+    # @param to [String] End date (YYYY-MM-DD)
+    # @return [Hash] Detailed analytics report
+    def analytics_report(from:, to:)
+      dashboard_post('analytics/report', { from: from, to: to })
+    end
+
+    # Retrieve market analytics
+    #
+    # Fetches market-level analytics data.
+    #
+    # @param from [String] Start date (YYYY-MM-DD)
+    # @param to [String] End date (YYYY-MM-DD)
+    # @return [Hash] Market analytics data
+    def market_analytics(from:, to:)
+      dashboard_post('analytics/market', { from: from, to: to })
+    end
+
+    # Retrieve most booked hotels
+    #
+    # Fetches data on most booked hotels during a date range.
+    #
+    # @param from [String] Start date (YYYY-MM-DD)
+    # @param to [String] End date (YYYY-MM-DD)
+    # @return [Array] List of most booked hotels
+    def most_booked_hotels(from:, to:)
+      dashboard_post('analytics/top-hotels', { from: from, to: to })
+    end
+  end
+end

data/lib/liteapi/booking.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Liteapi
+  module Booking
+    # Pre-book a rate to confirm availability and pricing
+    #
+    # Confirms if the room and rates are still available. Returns a prebook_id
+    # needed for the final booking.
+    #
+    # @param offer_id [String] The offer/rate ID from full_rates
+    # @return [Hash] Prebook confirmation with prebook_id
+    def prebook(offer_id:)
+      book_post('rates/prebook', { offerId: offer_id })
+    end
+
+    # Complete a booking
+    #
+    # Confirms the booking with guest and payment information.
+    #
+    # @param prebook_id [String] The prebook ID from prebook response
+    # @param guest [Hash] Guest information (first_name, last_name, email)
+    # @param payment [Hash] Payment information (card holder name, number, expiry, cvc)
+    # @param client_reference [String, nil] Your reference for this booking
+    # @return [Hash] Booking confirmation with booking_id
+    def book(prebook_id:, guest:, payment:, client_reference: nil)
+      body = {
+        prebookId: prebook_id,
+        guestInfo: {
+          guestFirstName: guest[:first_name],
+          guestLastName: guest[:last_name],
+          guestEmail: guest[:email]
+        },
+        paymentMethod: {
+          holderName: payment[:holder_name],
+          paymentMethodId: payment[:payment_method_id] || 'creditCard',
+          cardNumber: payment[:card_number],
+          expireDate: payment[:expire_date],
+          cvc: payment[:cvc]
+        }
+      }
+      body[:clientReference] = client_reference if client_reference
+
+      book_post('rates/book', body)
+    end
+
+    # List bookings by client reference
+    #
+    # @param client_reference [String] Your reference to search for
+    # @return [Array] List of bookings
+    def bookings(client_reference:)
+      book_get('bookings', clientReference: client_reference)
+    end
+
+    # Retrieve a specific booking
+    #
+    # @param booking_id [String] The booking ID
+    # @return [Hash] Booking details
+    def booking(booking_id)
+      book_get("bookings/#{booking_id}")
+    end
+
+    # Cancel a booking
+    #
+    # Cancellation success depends on the cancellation policy.
+    # Non-refundable bookings or those past the cancellation date cannot be cancelled.
+    #
+    # @param booking_id [String] The booking ID to cancel
+    # @return [Hash] Cancellation confirmation
+    def cancel_booking(booking_id)
+      book_put("bookings/#{booking_id}")
+    end
+  end
+end

data/lib/liteapi/client.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Liteapi
+  class Client
+    include StaticData
+    include Rates
+    include Booking
+    include Guests
+    include Vouchers
+    include Analytics
+
+    attr_reader :api_key, :base_url, :book_base_url, :dashboard_base_url,
+                :timeout, :open_timeout, :max_retries
+
+    def initialize(api_key: nil, base_url: nil, book_base_url: nil, dashboard_base_url: nil,
+                   timeout: nil, open_timeout: nil, max_retries: nil)
+      config = Liteapi.configuration
+
+      @api_key = api_key || config.api_key
+      @base_url = base_url || config.base_url
+      @book_base_url = book_base_url || config.book_base_url
+      @dashboard_base_url = dashboard_base_url || config.dashboard_base_url
+      @timeout = timeout || config.timeout
+      @open_timeout = open_timeout || config.open_timeout
+      @max_retries = max_retries || config.max_retries
+
+      validate_api_key!
+    end
+
+    private
+
+    def validate_api_key!
+      return if @api_key && !@api_key.empty?
+
+      raise Liteapi::Error, 'API key is required. Set via Liteapi.configure or pass api_key: to Client.new'
+    end
+
+    def connection
+      @connection ||= Connection.new(
+        api_key: @api_key,
+        base_url: @base_url,
+        timeout: @timeout,
+        open_timeout: @open_timeout,
+        max_retries: @max_retries
+      )
+    end
+
+    def book_connection
+      @book_connection ||= Connection.new(
+        api_key: @api_key,
+        base_url: @book_base_url,
+        timeout: @timeout,
+        open_timeout: @open_timeout,
+        max_retries: @max_retries
+      )
+    end
+
+    def dashboard_connection
+      @dashboard_connection ||= Connection.new(
+        api_key: @api_key,
+        base_url: @dashboard_base_url,
+        timeout: @timeout,
+        open_timeout: @open_timeout,
+        max_retries: @max_retries
+      )
+    end
+
+    def get(path, params = {})
+      connection.get(path, params)
+    end
+
+    def post(path, body = {})
+      connection.post(path, body)
+    end
+
+    def put(path, body = {})
+      connection.put(path, body)
+    end
+
+    def book_get(path, params = {})
+      book_connection.get(path, params)
+    end
+
+    def book_post(path, body = {})
+      book_connection.post(path, body)
+    end
+
+    def book_put(path, body = {})
+      book_connection.put(path, body)
+    end
+
+    def dashboard_get(path, params = {})
+      dashboard_connection.get(path, params)
+    end
+
+    def dashboard_post(path, body = {})
+      dashboard_connection.post(path, body)
+    end
+  end
+end

data/lib/liteapi/configuration.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Liteapi
+  class Configuration
+    attr_accessor :api_key, :base_url, :book_base_url, :dashboard_base_url,
+                  :timeout, :open_timeout, :max_retries
+
+    DEFAULT_BASE_URL = 'https://api.liteapi.travel/v3.0'
+    DEFAULT_BOOK_BASE_URL = 'https://book.liteapi.travel/v3.0'
+    DEFAULT_DASHBOARD_BASE_URL = 'https://da.liteapi.travel'
+    DEFAULT_TIMEOUT = 30
+    DEFAULT_OPEN_TIMEOUT = 10
+    DEFAULT_MAX_RETRIES = 3
+
+    def initialize
+      @api_key = ENV.fetch('LITEAPI_API_KEY', nil)
+      @base_url = DEFAULT_BASE_URL
+      @book_base_url = DEFAULT_BOOK_BASE_URL
+      @dashboard_base_url = DEFAULT_DASHBOARD_BASE_URL
+      @timeout = DEFAULT_TIMEOUT
+      @open_timeout = DEFAULT_OPEN_TIMEOUT
+      @max_retries = DEFAULT_MAX_RETRIES
+    end
+  end
+end

data/lib/liteapi/connection.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/retry'
+
+module Liteapi
+  class Connection
+    RETRY_STATUSES = [429, 500, 502, 503, 504].freeze
+
+    def initialize(api_key:, base_url:, timeout:, open_timeout:, max_retries:)
+      @api_key = api_key
+      @base_url = base_url
+      @timeout = timeout
+      @open_timeout = open_timeout
+      @max_retries = max_retries
+    end
+
+    def get(path, params = {})
+      request(:get, path, params)
+    end
+
+    def post(path, body = {})
+      request(:post, path, body)
+    end
+
+    def put(path, body = {})
+      request(:put, path, body)
+    end
+
+    private
+
+    def request(method, path, payload)
+      response = connection.public_send(method, path) do |req|
+        case method
+        when :get
+          req.params = payload if payload.any?
+        when :post, :put
+          req.body = payload
+        end
+      end
+
+      handle_response(response)
+    rescue Faraday::TimeoutError
+      raise Liteapi::Error, 'Request timed out'
+    rescue Faraday::ConnectionFailed
+      raise Liteapi::Error, 'Connection failed'
+    end
+
+    def handle_response(response)
+      body = response.body || {}
+
+      case response.status
+      when 200..299
+        body['data']
+      when 401
+        raise AuthenticationError.new(
+          error_message(body),
+          status: response.status,
+          code: body.dig('error', 'code'),
+          response: body
+        )
+      when 404
+        raise NotFoundError.new(
+          error_message(body),
+          status: response.status,
+          code: body.dig('error', 'code'),
+          response: body
+        )
+      when 422
+        raise ValidationError.new(
+          error_message(body),
+          status: response.status,
+          code: body.dig('error', 'code'),
+          response: body
+        )
+      when 429
+        raise RateLimitError.new(
+          error_message(body),
+          status: response.status,
+          code: body.dig('error', 'code'),
+          response: body
+        )
+      when 400..499
+        raise ClientError.new(
+          error_message(body),
+          status: response.status,
+          code: body.dig('error', 'code'),
+          response: body
+        )
+      when 500..599
+        raise ServerError.new(
+          error_message(body),
+          status: response.status,
+          code: body.dig('error', 'code'),
+          response: body
+        )
+      else
+        raise APIError.new(
+          "Unexpected response status: #{response.status}",
+          status: response.status,
+          response: body
+        )
+      end
+    end
+
+    def error_message(body)
+      body.dig('error', 'message') || body['message'] || 'Unknown error'
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: @base_url) do |f|
+        f.request :json
+        f.response :json
+        f.request :retry, retry_options
+        f.options.timeout = @timeout
+        f.options.open_timeout = @open_timeout
+        f.headers['X-API-Key'] = @api_key
+        f.headers['Accept'] = 'application/json'
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def retry_options
+      {
+        max: @max_retries,
+        interval: 0.5,
+        interval_randomness: 0.5,
+        backoff_factor: 2,
+        retry_statuses: RETRY_STATUSES,
+        retry_block: ->(_env, _options, retries, exception) {
+          # Could add logging here if needed
+        }
+      }
+    end
+  end
+end

data/lib/liteapi/errors.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Liteapi
+  class Error < StandardError; end
+
+  class APIError < Error
+    attr_reader :status, :code, :response
+
+    def initialize(message = nil, status: nil, code: nil, response: nil)
+      @status = status
+      @code = code
+      @response = response
+      super(message)
+    end
+  end
+
+  class ClientError < APIError; end
+  class ServerError < APIError; end
+
+  class AuthenticationError < ClientError; end
+  class NotFoundError < ClientError; end
+  class RateLimitError < ClientError; end
+  class ValidationError < ClientError; end
+end

data/lib/liteapi/guests.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Liteapi
+  module Guests
+    # Get loyalty program status
+    #
+    # Returns current loyalty program settings including status and cashback rates.
+    #
+    # @return [Hash] Loyalty program details
+    def loyalty
+      get('guests/loyalty')
+    end
+
+    # Enable loyalty program
+    #
+    # Creates a new loyalty program with specified settings.
+    #
+    # @param status [String] Program status ('enabled' or 'disabled')
+    # @param cashback_rate [Float] Cashback rate (e.g., 0.03 = 3%)
+    # @return [Hash] Loyalty program details
+    def enable_loyalty(status:, cashback_rate:)
+      post('guests/loyalty', {
+        status: status,
+        cashbackRate: cashback_rate
+      })
+    end
+
+    # Update loyalty program
+    #
+    # Updates existing loyalty program settings.
+    #
+    # @param status [String] Program status ('enabled' or 'disabled')
+    # @param cashback_rate [Float] Cashback rate (e.g., 0.03 = 3%)
+    # @return [Hash] Updated loyalty program details
+    def update_loyalty(status:, cashback_rate:)
+      put('guests/loyalty', {
+        status: status,
+        cashbackRate: cashback_rate
+      })
+    end
+
+    # Get guest details
+    #
+    # Retrieves detailed information about a guest including personal data,
+    # loyalty points, and booking history.
+    #
+    # @param guest_id [String, Integer] Guest identifier
+    # @return [Hash] Guest details
+    def guest(guest_id)
+      get("guests/#{guest_id}")
+    end
+
+    # Get guest bookings
+    #
+    # Retrieves all bookings for a specific guest with loyalty points
+    # and cashback information.
+    #
+    # @param guest_id [String, Integer] Guest identifier
+    # @return [Array] List of guest bookings
+    def guest_bookings(guest_id)
+      get("guests/#{guest_id}/bookings")
+    end
+  end
+end

data/lib/liteapi/rates.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Liteapi
+  module Rates
+    # Search for full rates and availability for hotels
+    #
+    # Returns all available rooms with rates, cancellation policies for a list of hotel IDs.
+    # Includes loyalty rewards if guest_id is provided.
+    #
+    # @param hotel_ids [Array<String>] List of hotel IDs to search
+    # @param checkin [String] Check-in date (YYYY-MM-DD)
+    # @param checkout [String] Check-out date (YYYY-MM-DD)
+    # @param occupancies [Array<Hash>] Room occupancies, each with :rooms, :adults, :children (ages array)
+    # @param guest_nationality [String] Guest nationality (ISO-2)
+    # @param currency [String] Currency code
+    # @param guest_id [String, nil] Guest ID for loyalty pricing
+    # @return [Hash] Rates and availability data
+    #
+    # @example
+    #   client.full_rates(
+    #     hotel_ids: ['lp1234', 'lp5678'],
+    #     checkin: '2025-03-01',
+    #     checkout: '2025-03-03',
+    #     occupancies: [{ rooms: 1, adults: 2, children: [5, 10] }],
+    #     guest_nationality: 'US',
+    #     currency: 'USD'
+    #   )
+    def full_rates(hotel_ids:, checkin:, checkout:, occupancies:, guest_nationality:, currency:,
+                   guest_id: nil)
+      body = {
+        hotelIds: hotel_ids,
+        checkin: checkin,
+        checkout: checkout,
+        occupancies: occupancies,
+        guestNationality: guest_nationality,
+        currency: currency
+      }
+      body[:guestId] = guest_id if guest_id
+
+      post('hotels/rates', body)
+    end
+
+    # Search for minimum rates for hotels
+    #
+    # Returns only the minimum rate per hotel for quick comparisons.
+    #
+    # @param hotel_ids [Array<String>] List of hotel IDs to search
+    # @param checkin [String] Check-in date (YYYY-MM-DD)
+    # @param checkout [String] Check-out date (YYYY-MM-DD)
+    # @param occupancies [Array<Hash>] Room occupancies, each with :rooms, :adults, :children (ages array)
+    # @param guest_nationality [String] Guest nationality (ISO-2)
+    # @param currency [String] Currency code
+    # @return [Hash] Minimum rates data
+    #
+    # @example
+    #   client.min_rates(
+    #     hotel_ids: ['lp1234'],
+    #     checkin: '2025-03-01',
+    #     checkout: '2025-03-03',
+    #     occupancies: [{ rooms: 1, adults: 2 }],
+    #     guest_nationality: 'US',
+    #     currency: 'USD'
+    #   )
+    def min_rates(hotel_ids:, checkin:, checkout:, occupancies:, guest_nationality:, currency:)
+      body = {
+        hotelIds: hotel_ids,
+        checkin: checkin,
+        checkout: checkout,
+        occupancies: occupancies,
+        guestNationality: guest_nationality,
+        currency: currency
+      }
+
+      post('hotels/min-rates', body)
+    end
+  end
+end

data/lib/liteapi/static_data.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Liteapi
+  module StaticData
+    # Returns list of all countries with ISO-2 codes
+    def countries
+      get('data/countries')
+    end
+
+    # Returns list of cities for a country
+    #
+    # @param country_code [String] ISO-2 country code (e.g., 'SG', 'US')
+    def cities(country_code:)
+      get('data/cities', countryCode: country_code)
+    end
+
+    # Search for places and areas
+    #
+    # @param query [String] Search text (e.g., 'Rome', 'Manhattan')
+    # @param type [String, nil] Filter by place type (e.g., 'hotel')
+    # @param language [String] Language for results (default: 'en')
+    def places(query:, type: nil, language: 'en')
+      params = { textQuery: query, language: language }
+      params[:type] = type if type
+      get('data/places', params)
+    end
+
+    # Returns all available currency codes
+    def currencies
+      get('data/currencies')
+    end
+
+    # Returns IATA codes for all airports
+    def iata_codes
+      get('data/iataCodes')
+    end
+
+    # Returns list of hotel facility types
+    def hotel_facilities
+      get('data/facilities')
+    end
+
+    # Returns list of hotel types (Hotel, Hostel, Resort, etc.)
+    def hotel_types
+      get('data/hotelTypes')
+    end
+
+    # Returns list of hotel chains
+    def hotel_chains
+      get('data/chains')
+    end
+
+    # Search for hotels
+    #
+    # @param country_code [String] ISO-2 country code (required)
+    # @param city_name [String, nil] Filter by city name
+    # @param latitude [Float, nil] Latitude for geo search
+    # @param longitude [Float, nil] Longitude for geo search
+    # @param radius [Integer, nil] Search radius in km (for geo search)
+    # @param language [String] Language for results (default: 'en')
+    def hotels(country_code:, city_name: nil, latitude: nil, longitude: nil, radius: nil, language: 'en')
+      params = { countryCode: country_code, language: language }
+      params[:cityName] = city_name if city_name
+      params[:latitude] = latitude if latitude
+      params[:longitude] = longitude if longitude
+      params[:radius] = radius if radius
+      get('data/hotels', params)
+    end
+
+    # Get detailed hotel information
+    #
+    # @param hotel_id [String] Hotel identifier
+    # @param language [String, nil] Language for results
+    def hotel(hotel_id, language: nil)
+      params = { hotelId: hotel_id }
+      params[:language] = language if language
+      get('data/hotel', params)
+    end
+
+    # Get hotel reviews with optional sentiment analysis
+    #
+    # @param hotel_id [String] Hotel identifier
+    # @param limit [Integer, nil] Maximum reviews to return (max 1000)
+    # @param sentiment [Boolean] Include sentiment analysis
+    def hotel_reviews(hotel_id:, limit: nil, sentiment: false)
+      params = { hotelId: hotel_id }
+      params[:limit] = limit if limit
+      params[:getSentiment] = sentiment if sentiment
+      get('data/reviews', params)
+    end
+  end
+end

data/lib/liteapi/version.rb

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