liteapi 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c44b103b3e33f46ee4bbc5edeb75122db504a7a2de724d3f8f09f057a8082c10
-  data.tar.gz: a0b067fff874a08a078dfcec38f71d68b4c82a7cdc93f58229b1949a14b222f2
+  metadata.gz: '08a9d9d70ebb966ca94dc5b5da0038346c22444d301ab2591fa874c91ae65676'
+  data.tar.gz: 518f4ec38d0cae6ba00e2aac542e58333ee8ed01bb282de2808cb2b67e9a6761
 SHA512:
-  metadata.gz: 446a6cb21d2a614050ced6642724a214f5d14e91fb0938e20dedf4a1288c9ea2003b85d14dbfeb5ef996f5b7c429cb740841a6247d8a3f0ce4bfa68cd1c28d02
-  data.tar.gz: 2685b0fe62ea0c1cd67fc85de9809ec818a6277e3341e6bd02e050b42d424d3c3fd6d329b1e205836c36fb9822ceebfc0d9b559221468ccb7dfbbc3f54922e32
+  metadata.gz: 657351d9a1174cde8e6425236c0e0cca813f3c4784adcffc68ee97e80f5306824ba47f035fb32cde698f38d299993834e7d3995a341862ffc1a8766244a7876f
+  data.tar.gz: 781c345554af02201d60f6db7bd93a7d371690b976e7312eb217d56f2c4c0962e49a101342daef67cea1f5695b5d7d02f93f3cee47320430b220bf2e1e6b9705

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.2.0] - 2025-01-12
+
+### Changed
+
+- **Dynamic parameters**: All methods now accept arbitrary keyword arguments that are automatically converted from Ruby `snake_case` to API `camelCase`. This allows using new API parameters without SDK updates.
+- Nested hashes and arrays are recursively transformed for POST/PUT request bodies.
+- Array parameters in GET requests are joined with commas for query strings.
+
+### Fixed
+
+- Properly handle nested structures like `occupancies` in rates requests.
+
 ## [0.1.0] - 2025-01-12
 
 ### Added

data/README.md

@@ -90,6 +90,12 @@ client = Liteapi::Client.new(api_key: 'your_api_key')
 | `open_timeout` | `10` | Connection timeout in seconds |
 | `max_retries` | `3` | Retries on 429/5xx errors |
 
+### API Documentation
+
+For the full list of available parameters for each endpoint, see the official API documentation at **[docs.liteapi.travel](https://docs.liteapi.travel)**.
+
+This SDK uses Ruby-style `snake_case` parameter names which are automatically converted to the API's `camelCase` format. For example, `country_code` becomes `countryCode`.
+
 ---
 
 # Static Data

data/lib/liteapi/analytics.rb

@@ -4,46 +4,34 @@ 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 })
+    # @example
+    #   client.weekly_analytics(from: '2025-01-01', to: '2025-01-07')
+    def weekly_analytics(**params)
+      dashboard_post('analytics/weekly', prepare_body_params(params))
     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 })
+    # @example
+    #   client.analytics_report(from: '2025-01-01', to: '2025-01-31')
+    def analytics_report(**params)
+      dashboard_post('analytics/report', prepare_body_params(params))
     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 })
+    # @example
+    #   client.market_analytics(from: '2025-01-01', to: '2025-01-31')
+    def market_analytics(**params)
+      dashboard_post('analytics/market', prepare_body_params(params))
     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 })
+    # @example
+    #   client.most_booked_hotels(from: '2025-01-01', to: '2025-01-31')
+    def most_booked_hotels(**params)
+      dashboard_post('analytics/top-hotels', prepare_body_params(params))
     end
   end
 end

data/lib/liteapi/booking.rb

@@ -4,68 +4,53 @@ 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 })
+    # @example
+    #   client.prebook(offer_id: 'offer_abc123')
+    def prebook(**params)
+      book_post('rates/prebook', prepare_body_params(params))
     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)
+    # @example
+    #   client.book(
+    #     prebook_id: 'prebook_123',
+    #     guest_info: {
+    #       guest_first_name: 'John',
+    #       guest_last_name: 'Doe',
+    #       guest_email: 'john@example.com'
+    #     },
+    #     payment_method: {
+    #       holder_name: 'John Doe',
+    #       card_number: '4111111111111111',
+    #       expire_date: '12/25',
+    #       cvc: '123'
+    #     }
+    #   )
+    def book(**params)
+      book_post('rates/book', prepare_body_params(params))
     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)
+    # @example
+    #   client.bookings(client_reference: 'my-booking-123')
+    def bookings(**params)
+      book_get('bookings', prepare_query_params(params))
     end
 
     # Retrieve a specific booking
     #
-    # @param booking_id [String] The booking ID
-    # @return [Hash] Booking details
+    # @example
+    #   client.booking('booking_abc123')
     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
+    # @example
+    #   client.cancel_booking('booking_abc123')
     def cancel_booking(booking_id)
       book_put("bookings/#{booking_id}")
     end

data/lib/liteapi/client.rb

@@ -96,5 +96,36 @@ module Liteapi
     def dashboard_post(path, body = {})
       dashboard_connection.post(path, body)
     end
+
+    # Convert Ruby snake_case key to API camelCase
+    def camelize_key(key)
+      key.to_s.gsub(/_([a-z])/) { ::Regexp.last_match(1).upcase }
+    end
+
+    # Recursively convert keys from snake_case to camelCase
+    def deep_camelize_keys(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) do |(key, value), result|
+          result[camelize_key(key)] = deep_camelize_keys(value)
+        end
+      when Array
+        obj.map { |item| deep_camelize_keys(item) }
+      else
+        obj
+      end
+    end
+
+    # Prepare query params for GET requests (joins arrays with commas)
+    def prepare_query_params(params)
+      deep_camelize_keys(params.compact).transform_values do |v|
+        v.is_a?(Array) ? v.join(',') : v
+      end
+    end
+
+    # Prepare body params for POST/PUT requests (keeps arrays as arrays)
+    def prepare_body_params(params)
+      deep_camelize_keys(params.compact)
+    end
   end
 end

data/lib/liteapi/guests.rb

@@ -4,59 +4,40 @@ module Liteapi
   module Guests
     # Get loyalty program status
     #
-    # Returns current loyalty program settings including status and cashback rates.
-    #
-    # @return [Hash] Loyalty program details
+    # @example
+    #   client.loyalty
     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
-      })
+    # @example
+    #   client.enable_loyalty(status: 'enabled', cashback_rate: 0.03)
+    def enable_loyalty(**params)
+      post('guests/loyalty', prepare_body_params(params))
     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
-      })
+    # @example
+    #   client.update_loyalty(status: 'enabled', cashback_rate: 0.05)
+    def update_loyalty(**params)
+      put('guests/loyalty', prepare_body_params(params))
     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
+    # @example
+    #   client.guest(123)
     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
+    # @example
+    #   client.guest_bookings(123)
     def guest_bookings(guest_id)
       get("guests/#{guest_id}/bookings")
     end

data/lib/liteapi/rates.rb

@@ -5,16 +5,6 @@ module Liteapi
     # 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(
@@ -22,56 +12,28 @@ module Liteapi
     #     checkin: '2025-03-01',
     #     checkout: '2025-03-03',
     #     occupancies: [{ rooms: 1, adults: 2, children: [5, 10] }],
-    #     guest_nationality: 'US',
-    #     currency: 'USD'
+    #     currency: 'USD',
+    #     guest_nationality: 'US'
     #   )
-    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)
+    def full_rates(**params)
+      post('hotels/rates', prepare_body_params(params))
     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'
+    #     currency: 'USD',
+    #     guest_nationality: 'US'
     #   )
-    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)
+    def min_rates(**params)
+      post('hotels/min-rates', prepare_body_params(params))
     end
   end
 end

data/lib/liteapi/static_data.rb

@@ -9,20 +9,21 @@ module Liteapi
 
     # 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)
+    # @example
+    #   client.cities(country_code: 'IT')
+    def cities(**params)
+      get('data/cities', prepare_query_params(params))
     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)
+    # @example
+    #   client.places(query: 'Rome')
+    #   client.places(query: 'Rome', type: 'hotel', language: 'it')
+    def places(query:, **params)
+      params[:text_query] = query
+      params[:language] ||= 'en'
+      get('data/places', prepare_query_params(params))
     end
 
     # Returns all available currency codes
@@ -52,41 +53,43 @@ module Liteapi
 
     # 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)
+    # Supports multiple search approaches: by city, coordinates, place ID, or hotel IDs.
+    # All parameters are passed through to the API with snake_case converted to camelCase.
+    #
+    # @example Search by country and city
+    #   client.hotels(country_code: 'IT', city_name: 'Rome')
+    #
+    # @example Search by hotel IDs
+    #   client.hotels(hotel_ids: ['lp1234', 'lp5678'])
+    #
+    # @example AI-powered search
+    #   client.hotels(ai_search: 'luxury beach resort with pool')
+    #
+    # @example Search by place ID
+    #   client.hotels(place_id: 'place_abc123')
+    def hotels(**params)
+      params[:language] ||= 'en'
+      get('data/hotels', prepare_query_params(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)
+    # @example
+    #   client.hotel('lp1897')
+    #   client.hotel('lp1897', language: 'fr')
+    def hotel(hotel_id, **params)
+      params[:hotel_id] = hotel_id
+      get('data/hotel', prepare_query_params(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)
+    # @example
+    #   client.hotel_reviews(hotel_id: 'lp1897')
+    #   client.hotel_reviews(hotel_id: 'lp1897', limit: 100, get_sentiment: true)
+    def hotel_reviews(hotel_id:, **params)
+      params[:hotel_id] = hotel_id
+      get('data/reviews', prepare_query_params(params))
     end
   end
 end

data/lib/liteapi/version.rb

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

data/lib/liteapi/vouchers.rb

@@ -4,97 +4,53 @@ module Liteapi
   module Vouchers
     # List all vouchers
     #
-    # Retrieves all available vouchers including codes, discounts, and validity.
-    #
-    # @return [Array] List of voucher objects
+    # @example
+    #   client.vouchers
     def vouchers
       get('vouchers')
     end
 
     # Get voucher details
     #
-    # Retrieves details for a specific voucher.
-    #
-    # @param voucher_id [String, Integer] Voucher identifier
-    # @return [Hash] Voucher details
+    # @example
+    #   client.voucher(42)
     def voucher(voucher_id)
       get("vouchers/#{voucher_id}")
     end
 
     # Create a voucher
     #
-    # Creates a new voucher with specified settings.
-    #
-    # @param voucher_code [String] Unique voucher code
-    # @param discount_type [String] Type of discount ('percentage' or 'fixed')
-    # @param discount_value [Float] Discount value
-    # @param minimum_spend [Float] Minimum spend to apply voucher
-    # @param maximum_discount_amount [Float] Maximum discount amount
-    # @param currency [String] Currency code
-    # @param validity_start [String] Start date (YYYY-MM-DD)
-    # @param validity_end [String] End date (YYYY-MM-DD)
-    # @param usages_limit [Integer] Maximum redemptions
-    # @param status [String] Voucher status ('active' or 'inactive')
-    # @return [Hash] Created voucher confirmation
-    def create_voucher(voucher_code:, discount_type:, discount_value:, minimum_spend:,
-                       maximum_discount_amount:, currency:, validity_start:, validity_end:,
-                       usages_limit:, status:)
-      post('vouchers', {
-        voucher_code: voucher_code,
-        discount_type: discount_type,
-        discount_value: discount_value,
-        minimum_spend: minimum_spend,
-        maximum_discount_amount: maximum_discount_amount,
-        currency: currency,
-        validity_start: validity_start,
-        validity_end: validity_end,
-        usages_limit: usages_limit,
-        status: status
-      })
+    # @example
+    #   client.create_voucher(
+    #     voucher_code: 'SUMMER20',
+    #     discount_type: 'percentage',
+    #     discount_value: 20,
+    #     minimum_spend: 100,
+    #     maximum_discount_amount: 50,
+    #     currency: 'USD',
+    #     validity_start: '2025-06-01',
+    #     validity_end: '2025-08-31',
+    #     usages_limit: 100,
+    #     status: 'active'
+    #   )
+    def create_voucher(**params)
+      post('vouchers', prepare_body_params(params))
     end
 
     # Update a voucher
     #
-    # Updates an existing voucher's settings.
-    #
-    # @param voucher_id [String, Integer] Voucher identifier
-    # @param voucher_code [String] Unique voucher code
-    # @param discount_type [String] Type of discount
-    # @param discount_value [Float] Discount value
-    # @param minimum_spend [Float] Minimum spend
-    # @param maximum_discount_amount [Float] Maximum discount
-    # @param currency [String] Currency code
-    # @param validity_start [String] Start date (YYYY-MM-DD)
-    # @param validity_end [String] End date (YYYY-MM-DD)
-    # @param usages_limit [Integer] Maximum redemptions
-    # @param status [String] Voucher status
-    # @return [Hash] Update confirmation
-    def update_voucher(voucher_id, voucher_code:, discount_type:, discount_value:, minimum_spend:,
-                       maximum_discount_amount:, currency:, validity_start:, validity_end:,
-                       usages_limit:, status:)
-      put("vouchers/#{voucher_id}", {
-        voucher_code: voucher_code,
-        discount_type: discount_type,
-        discount_value: discount_value,
-        minimum_spend: minimum_spend,
-        maximum_discount_amount: maximum_discount_amount,
-        currency: currency,
-        validity_start: validity_start,
-        validity_end: validity_end,
-        usages_limit: usages_limit,
-        status: status
-      })
+    # @example
+    #   client.update_voucher(42, voucher_code: 'SUMMER25', discount_value: 25, ...)
+    def update_voucher(voucher_id, **params)
+      put("vouchers/#{voucher_id}", prepare_body_params(params))
     end
 
     # Update voucher status
     #
-    # Activates or deactivates a voucher.
-    #
-    # @param voucher_id [String, Integer] Voucher identifier
-    # @param status [String] New status ('active' or 'inactive')
-    # @return [Hash] Update confirmation
-    def update_voucher_status(voucher_id, status:)
-      put("vouchers/#{voucher_id}/status", { status: status })
+    # @example
+    #   client.update_voucher_status(42, status: 'inactive')
+    def update_voucher_status(voucher_id, **params)
+      put("vouchers/#{voucher_id}/status", prepare_body_params(params))
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: liteapi
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Alan Bradburne