channex 0.1.0

data/lib/channex/resources/photos.rb

@@ -0,0 +1,117 @@
+module Channex
+  module Resources
+    # Photos API resource
+    #
+    # Photos are associated with Properties and optionally with Room Types.
+    # Position 0 is used as the cover photo.
+    #
+    # @example List photos for a property
+    #   client.photos.list(property_id: "property-uuid")
+    #
+    # @example Create a photo from URL
+    #   client.photos.create(
+    #     property_id: "property-uuid",
+    #     url: "https://example.com/photo.jpg",
+    #     position: 0,
+    #     description: "Hotel Lobby",
+    #     kind: "photo"
+    #   )
+    #
+    # @example Upload a photo file then create it
+    #   # Step 1: Upload the file to get a temporary URL
+    #   upload_response = client.photos.upload("/path/to/photo.jpg")
+    #   temp_url = upload_response.body["url"]
+    #
+    #   # Step 2: Create the photo using the temporary URL
+    #   client.photos.create(
+    #     property_id: "property-uuid",
+    #     url: temp_url,
+    #     position: 0
+    #   )
+    #
+    # @see https://docs.channex.io/api-v.1-documentation/photos-collection
+    #
+    class Photos < Resource
+      KINDS = %w[photo ad menu].freeze
+
+      # Upload a photo file and get a temporary URL
+      #
+      # This uploads the file to Channex's servers and returns a temporary URL
+      # that can then be used with the create method.
+      #
+      # @param file_path [String] Path to the photo file
+      # @return [Response] Response with "url" in body containing temporary URL
+      #
+      # @example
+      #   response = client.photos.upload("/path/to/photo.jpg")
+      #   temp_url = response.body["url"]
+      #   # => "https://ams3.digitaloceanspaces.com/temporaryphotos/..."
+      def upload(file_path)
+        uri = URI("#{client.configuration.api_url}#{resource_path}/upload")
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.read_timeout = client.configuration.timeout
+        http.open_timeout = client.configuration.open_timeout
+
+        request = Net::HTTP::Post.new(uri)
+        request["user-api-key"] = client.api_key
+
+        file = File.open(file_path, "rb")
+        filename = File.basename(file_path)
+        boundary = "----RubyMultipartPost#{rand(1000000)}"
+
+        request["Content-Type"] = "multipart/form-data; boundary=#{boundary}"
+        request.body = build_multipart_body(file, filename, boundary)
+        file.close
+
+        response = http.request(request)
+        Response.new(response)
+      end
+
+      # Reorder photos
+      #
+      # @param photos [Array<Hash>] Array of { id: "uuid", position: 0 }
+      # @return [Response]
+      def reorder(photos)
+        client.post("#{resource_path}/reorder", body: {photos: photos})
+      end
+
+      protected
+
+      def resource_path
+        "/photos"
+      end
+
+      def filter_keys
+        %i[property_id room_type_id]
+      end
+
+      private
+
+      def build_multipart_body(file, filename, boundary)
+        body = []
+        body << "--#{boundary}\r\n"
+        body << "Content-Disposition: form-data; name=\"photo\"; filename=\"#{filename}\"\r\n"
+        body << "Content-Type: #{mime_type_for(filename)}\r\n\r\n"
+        body << file.read
+        body << "\r\n--#{boundary}--\r\n"
+        body.join
+      end
+
+      def mime_type_for(filename)
+        case File.extname(filename).downcase
+        when ".jpg", ".jpeg"
+          "image/jpeg"
+        when ".png"
+          "image/png"
+        when ".gif"
+          "image/gif"
+        when ".webp"
+          "image/webp"
+        else
+          "application/octet-stream"
+        end
+      end
+    end
+  end
+end

data/lib/channex/resources/properties.rb

@@ -0,0 +1,42 @@
+module Channex
+  module Resources
+    # Properties API resource
+    #
+    # A Property represents a physical premises - hotels, motels, lodges,
+    # cabins, chalets, luxury apartments, etc.
+    #
+    # @example List all properties
+    #   client.properties.list
+    #
+    # @example Create a property
+    #   client.properties.create(
+    #     title: "My Hotel",
+    #     currency: "USD",
+    #     timezone: "America/New_York",
+    #     property_type: "hotel",
+    #     settings: { allow_availability_autoupdate: true }
+    #   )
+    #
+    # @see https://docs.channex.io/api-v.1-documentation/hotels-collection
+    #
+    class Properties < Resource
+      # Retrieve property health status
+      #
+      # @param id [String] Property UUID
+      # @return [Response]
+      def health(id)
+        client.get("#{resource_path}/#{id}/health")
+      end
+
+      protected
+
+      def resource_path
+        "/properties"
+      end
+
+      def filter_keys
+        %i[group_id]
+      end
+    end
+  end
+end

data/lib/channex/resources/property_users.rb

@@ -0,0 +1,32 @@
+module Channex
+  module Resources
+    # Property Users API resource
+    #
+    # Property Users represent the association between users and properties,
+    # defining access permissions at the property level.
+    #
+    # @example List users for a property
+    #   client.property_users.list(property_id: "property-uuid")
+    #
+    # @example Add a user to a property
+    #   client.property_users.create(
+    #     property_id: "property-uuid",
+    #     user_id: "user-uuid",
+    #     role: "manager"
+    #   )
+    #
+    # @see https://docs.channex.io/api-v.1-documentation/property-users-collection
+    #
+    class PropertyUsers < Resource
+      protected
+
+      def resource_path
+        "/property_users"
+      end
+
+      def filter_keys
+        %i[property_id]
+      end
+    end
+  end
+end

data/lib/channex/resources/rate_plans.rb

@@ -0,0 +1,34 @@
+module Channex
+  module Resources
+    # Rate Plans API resource
+    #
+    # A Rate Plan is a pricing plan for how to sell your Room Types,
+    # containing information about prices and restrictions.
+    #
+    # @example List rate plans for a property
+    #   client.rate_plans.list(property_id: "property-uuid")
+    #
+    # @example Create a rate plan
+    #   client.rate_plans.create(
+    #     property_id: "property-uuid",
+    #     room_type_id: "room-type-uuid",
+    #     title: "Standard Rate",
+    #     sell_mode: "per_room",
+    #     rate_mode: "manual"
+    #   )
+    #
+    # @see https://docs.channex.io/api-v.1-documentation/rate-plans-collection
+    #
+    class RatePlans < Resource
+      protected
+
+      def resource_path
+        "/rate_plans"
+      end
+
+      def filter_keys
+        %i[property_id room_type_id]
+      end
+    end
+  end
+end

data/lib/channex/resources/restrictions.rb

@@ -0,0 +1,98 @@
+module Channex
+  module Resources
+    # Restrictions API resource
+    #
+    # Restrictions represent pricing and stay restrictions applied to rate plans.
+    # This includes rates, min/max stay, closed to arrival/departure, and stop sell.
+    #
+    # @example Get restrictions for a property
+    #   client.restrictions.list(
+    #     property_id: "property-uuid",
+    #     date_from: "2024-01-01",
+    #     date_to: "2024-01-31"
+    #   )
+    #
+    # @example Update restrictions (rates and stay rules)
+    #   client.restrictions.update([
+    #     {
+    #       property_id: "property-uuid",
+    #       rate_plan_id: "rate-plan-uuid",
+    #       date_from: "2024-01-15",
+    #       date_to: "2024-01-20",
+    #       rate: 15000,
+    #       min_stay_arrival: 2,
+    #       closed_to_arrival: false
+    #     }
+    #   ])
+    #
+    # @see https://docs.channex.io/api-v.1-documentation/ari
+    #
+    class Restrictions < Resource
+      # Get restrictions for a property within a date range
+      #
+      # @param property_id [String] Property UUID (required)
+      # @param date [String] Specific date (YYYY-MM-DD)
+      # @param date_from [String] Start date (YYYY-MM-DD)
+      # @param date_to [String] End date (YYYY-MM-DD)
+      # @param options [Hash] Additional options
+      # @return [Response]
+      def list(property_id:, date: nil, date_from: nil, date_to: nil, **options)
+        filter = options.delete(:filter) || {}
+        filter[:property_id] = property_id
+
+        if date
+          filter[:date] = date
+        else
+          filter[:date] = {}
+          filter[:date][:gte] = date_from if date_from
+          filter[:date][:lte] = date_to if date_to
+        end
+
+        client.get(resource_path, params: {filter: filter, **options})
+      end
+
+      # Update restrictions (rates and stay rules) for rate plans
+      #
+      # Each value in the array should contain all required fields including property_id.
+      # You can update multiple properties and rate plans in a single request.
+      #
+      # @param values [Array<Hash>] Array of restriction updates
+      #   Each hash can contain:
+      #   - property_id [String] Property UUID (required)
+      #   - rate_plan_id [String] Rate Plan UUID (required)
+      #   - date_from [String] Start date YYYY-MM-DD (required)
+      #   - date_to [String] End date YYYY-MM-DD (required)
+      #   - rate [Integer] Price (in smallest currency unit, e.g., cents)
+      #   - min_stay_arrival [Integer] Minimum stay if arriving on this date
+      #   - min_stay_through [Integer] Minimum stay passing through this date
+      #   - max_stay [Integer] Maximum stay (0 = no limit)
+      #   - closed_to_arrival [Boolean] Prevent arrivals on this date
+      #   - closed_to_departure [Boolean] Prevent departures on this date
+      #   - stop_sell [Boolean] Stop selling this rate plan
+      # @return [Response]
+      #
+      # @example Update rates and restrictions for a date range
+      #   client.restrictions.update([
+      #     {
+      #       property_id: "716305c4-561a-4561-a187-7f5b8aeb5920",
+      #       rate_plan_id: "bab451e7-9ab1-4cc4-aa16-107bf7bbabb2",
+      #       date_from: "2024-01-15",
+      #       date_to: "2024-01-20",
+      #       rate: 30000,
+      #       min_stay_arrival: 2,
+      #       closed_to_arrival: false,
+      #       stop_sell: false
+      #     }
+      #   ])
+      def update(values)
+        client.post(resource_path, body: {values: values})
+      end
+
+      protected
+
+      def resource_path
+        "/restrictions"
+      end
+    end
+  end
+end

data/lib/channex/resources/reviews.rb

@@ -0,0 +1,41 @@
+module Channex
+  module Resources
+    # Reviews API resource
+    #
+    # A review is what a guest wrote about a stay on Booking.com, Airbnb or
+    # Expedia, normalised by Channex: an overall score out of 10, per-category
+    # scores, the text and the property's reply.
+    #
+    # Requires the Messages & Reviews application to be installed on the
+    # property — without it every call in here answers 403 Forbidden.
+    #
+    # @example List a property's reviews
+    #   client.reviews.list(property_id: "property-uuid")
+    #
+    # @example Reply to a review
+    #   client.reviews.reply("review-uuid", reply: "Thank you for staying with us.")
+    #
+    # @see https://docs.channex.io/api-v.1-documentation/reviews-collection
+    #
+    class Reviews < Resource
+      # Reply to a review on the OTA
+      #
+      # @param id [String] Review UUID
+      # @param reply [String] Reply text
+      # @return [Response] The review, now replied
+      def reply(id, reply:)
+        client.post("#{resource_path}/#{id}/reply", body: {reply: {reply:}})
+      end
+
+      protected
+
+      def resource_path
+        "/reviews"
+      end
+
+      def filter_keys
+        %i[property_id booking_id]
+      end
+    end
+  end
+end

data/lib/channex/resources/room_types.rb

@@ -0,0 +1,34 @@
+module Channex
+  module Resources
+    # Room Types API resource
+    #
+    # Room Types represent the different types of rooms available at a property.
+    #
+    # @example List room types for a property
+    #   client.room_types.list(property_id: "property-uuid")
+    #
+    # @example Create a room type
+    #   client.room_types.create(
+    #     property_id: "property-uuid",
+    #     title: "Deluxe King Room",
+    #     count_of_rooms: 10,
+    #     occ_adults: 2,
+    #     occ_children: 1,
+    #     occ_infants: 1
+    #   )
+    #
+    # @see https://docs.channex.io/api-v.1-documentation/room-types-collection
+    #
+    class RoomTypes < Resource
+      protected
+
+      def resource_path
+        "/room_types"
+      end
+
+      def filter_keys
+        %i[property_id]
+      end
+    end
+  end
+end

data/lib/channex/resources/tax_sets.rb

@@ -0,0 +1,34 @@
+module Channex
+  module Resources
+    # Tax Sets API resource
+    #
+    # A Tax Set represents a group of Taxes applicable to your Rate Plan or Property.
+    # Each property can have many Tax Sets, but only one can be selected as
+    # the Default Tax Set, which is applied to each new Rate Plan automatically.
+    #
+    # @example List tax sets for a property
+    #   client.tax_sets.list(property_id: "property-uuid")
+    #
+    # @example Create a tax set
+    #   client.tax_sets.create(
+    #     property_id: "property-uuid",
+    #     title: "Standard Taxes",
+    #     taxes: ["tax-uuid-1", "tax-uuid-2"],
+    #     is_default: true
+    #   )
+    #
+    # @see https://docs.channex.io/api-v.1-documentation/taxes-and-tax-sets
+    #
+    class TaxSets < Resource
+      protected
+
+      def resource_path
+        "/tax_sets"
+      end
+
+      def filter_keys
+        %i[property_id]
+      end
+    end
+  end
+end

data/lib/channex/resources/taxes.rb

@@ -0,0 +1,60 @@
+module Channex
+  module Resources
+    # Taxes API resource
+    #
+    # A Tax represents a specific tax applicable to your Rate Plan or Property,
+    # such as VAT 20%, City Tax 1 EUR per Guest per Night, etc.
+    #
+    # @example List taxes for a property
+    #   client.taxes.list(property_id: "property-uuid")
+    #
+    # @example Create a percentage-based tax (VAT)
+    #   client.taxes.create(
+    #     property_id: "property-uuid",
+    #     title: "VAT",
+    #     logic: "percent",
+    #     type: "tax",
+    #     rate: "20.00",
+    #     is_inclusive: true
+    #   )
+    #
+    # @example Create a fixed amount tax (City Tax per person per night)
+    #   client.taxes.create(
+    #     property_id: "property-uuid",
+    #     title: "City Tax",
+    #     logic: "per_person_per_night",
+    #     type: "city tax",
+    #     rate: "2.00",
+    #     currency: "EUR",
+    #     is_inclusive: false
+    #   )
+    #
+    # @see https://docs.channex.io/api-v.1-documentation/taxes-and-tax-sets
+    #
+    class Taxes < Resource
+      # Logic types for tax calculation
+      LOGIC_TYPES = %w[
+        percent
+        per_room
+        per_room_per_night
+        per_person
+        per_person_per_night
+        per_night
+        per_booking
+      ].freeze
+
+      # Tax types
+      TAX_TYPES = ["tax", "fee", "city tax"].freeze
+
+      protected
+
+      def resource_path
+        "/taxes"
+      end
+
+      def filter_keys
+        %i[property_id]
+      end
+    end
+  end
+end

data/lib/channex/resources/webhooks.rb

@@ -0,0 +1,87 @@
+module Channex
+  module Resources
+    # Webhooks API resource
+    #
+    # Webhooks allow you to receive push notifications about changes
+    # in your property's data, including ARI changes and booking events.
+    #
+    # Available webhook events:
+    # - *: All events
+    # - ari: ARI changes (availability, rates, restrictions)
+    # - booking: All booking changes (new, modified, cancelled)
+    # - booking_new: Only new bookings
+    # - booking_modification: Only modified bookings
+    # - booking_cancellation: Only cancelled bookings
+    # - reservation_request: Airbnb reservation requests
+    # - new_channel: Channel connected
+    # - updated_channel: Channel updated
+    # - disconnected_channel: Channel disconnected
+    # - message: New message received
+    #
+    # ARI events support filtering by restriction type, room type, and rate plan:
+    #   Format: "ari:restrictions:room_type_ids:rate_plan_ids"
+    #   Example: "ari:rate:*:96a44e07-2158-43e4-8baa-8f6f56922ba8"
+    #
+    # @example Create a webhook for all events
+    #   client.webhooks.create(
+    #     property_id: "property-uuid",
+    #     callback_url: "https://your-domain.com/webhooks/channex",
+    #     event_mask: "*",
+    #     is_active: true,
+    #     send_data: true
+    #   )
+    #
+    # @example Create a webhook for specific rate plan changes
+    #   client.webhooks.create(
+    #     property_id: "property-uuid",
+    #     callback_url: "https://your-domain.com/webhooks/ari",
+    #     event_mask: "ari:rate:*:96a44e07-2158-43e4-8baa-8f6f56922ba8",
+    #     is_active: true,
+    #     send_data: true
+    #   )
+    #
+    # @see https://docs.channex.io/api-v.1-documentation/webhook-collection
+    #
+    class Webhooks < Resource
+      # Standard event types
+      EVENTS = %w[
+        ari
+        booking
+        booking_new
+        booking_modification
+        booking_cancellation
+        reservation_request
+        new_channel
+        updated_channel
+        disconnected_channel
+        message
+      ].freeze
+
+      # Test a webhook endpoint without saving
+      #
+      # @param attributes [Hash] Webhook attributes to test
+      # @return [Response]
+      def test_new(attributes)
+        client.post("#{resource_path}/test", body: {webhook: attributes})
+      end
+
+      # Test an existing webhook endpoint
+      #
+      # @param id [String] Webhook UUID
+      # @return [Response]
+      def test(id)
+        client.post("#{resource_path}/#{id}/test", body: {})
+      end
+
+      protected
+
+      def resource_path
+        "/webhooks"
+      end
+
+      def filter_keys
+        %i[property_id]
+      end
+    end
+  end
+end

data/lib/channex/resources.rb

@@ -0,0 +1,5 @@
+module Channex
+  # Namespace for all Channex API resource classes
+  module Resources
+  end
+end

data/lib/channex/response.rb

@@ -0,0 +1,102 @@
+module Channex
+  # Wraps API responses with convenient accessors
+  #
+  # Channex API responses follow this structure:
+  # - Success: { "data": {...} } or { "data": [...], "meta": {...} }
+  # - Error: { "error": {...} } or { "errors": {...} }
+  #
+  class Response
+    attr_reader :status, :headers, :raw_body, :body
+
+    def initialize(http_response)
+      @status = http_response.code.to_i
+      @headers = http_response.to_hash
+      @raw_body = http_response.body
+      @body = parse_body(http_response.body)
+    end
+
+    def success?
+      status >= 200 && status < 300
+    end
+
+    def data
+      body["data"]
+    end
+
+    def meta
+      body["meta"] || {}
+    end
+
+    # Returns error information from the response
+    #
+    # Channex API can return errors in two formats:
+    # - { "error": { "message": "...", "code": "..." } }
+    # - { "errors": { "code": "...", "title": "..." } }
+    #
+    # @return [Hash, nil] Error information or nil if no error
+    def error
+      body["error"] || body["errors"]
+    end
+
+    # Returns warnings from the response meta
+    #
+    # ARI updates can return partial success with warnings for invalid values.
+    #
+    # @return [Array] Array of warning objects
+    def warnings
+      meta["warnings"] || []
+    end
+
+    def pagination
+      @pagination ||= Pagination.new(meta)
+    end
+
+    private
+
+    def parse_body(body)
+      return {} if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      {"raw" => body}
+    end
+  end
+
+  # Pagination information from API responses
+  class Pagination
+    attr_reader :page, :limit, :total, :order
+
+    def initialize(meta)
+      @page = meta["page"]
+      @limit = meta["limit"]
+      @total = meta["total"]
+      @order = meta["order"]
+    end
+
+    def total_pages
+      return nil unless total && limit && limit > 0
+
+      (total.to_f / limit).ceil
+    end
+
+    def next_page
+      return nil unless page && total_pages
+
+      (page < total_pages) ? page + 1 : nil
+    end
+
+    def prev_page
+      return nil unless page
+
+      (page > 1) ? page - 1 : nil
+    end
+
+    def has_next?
+      !next_page.nil?
+    end
+
+    def has_prev?
+      !prev_page.nil?
+    end
+  end
+end

data/lib/channex/version.rb

@@ -0,0 +1,3 @@
+module Channex
+  VERSION = "0.1.0"
+end