channex 0.1.0

data/lib/channex/objects/message_thread.rb

@@ -0,0 +1,76 @@
+module Channex
+  module Objects
+    # A conversation between a guest and the property, as Channex unifies it
+    # across Booking.com, Airbnb and Expedia.
+    #
+    # Like {Message}, a thread arrives as a JSON:API resource node;
+    # {.from_resource} flattens the identifier and relationships into the
+    # attributes so the whole thread is one hash.
+    #
+    # A thread usually belongs to a booking, but not always: an Airbnb inquiry
+    # is a conversation about a stay that does not exist yet, so `booking_id`
+    # is nil until the guest books.
+    #
+    # @example
+    #   thread.title        # => "Maldonado Roxy"
+    #   thread.provider     # => "BookingCom"
+    #   thread.closed?      # => false
+    #   thread.last_message # => Channex::Objects::Message
+    #
+    class MessageThread < Channex::Object
+      attribute :id
+      attribute :title
+      attribute :provider
+      attribute :message_count
+      attribute :last_message, type: Message
+      attribute :last_message_received_at
+      attribute :inserted_at
+      attribute :updated_at
+
+      # Lifted out of `relationships`
+      attribute :booking_id
+      attribute :channel_id
+      attribute :property_id
+
+      # Flatten a JSON:API resource node into a thread
+      #
+      # @param node [Hash, nil] A `{"id", "attributes", "relationships"}` node
+      # @return [MessageThread, nil]
+      def self.from_resource(node)
+        return nil if node.nil?
+
+        attributes = node["attributes"] || {}
+        relationships = node["relationships"] || {}
+
+        new(
+          attributes.merge(
+            "id" => node["id"],
+            "booking_id" => relationships.dig("booking", "data", "id"),
+            "channel_id" => relationships.dig("channel", "data", "id"),
+            "property_id" => relationships.dig("property", "data", "id")
+          ).compact
+        )
+      end
+
+      # Whether the property closed the thread. Closed threads still accept
+      # messages; the flag is an inbox state, not a lock.
+      #
+      # @return [Boolean]
+      def closed?
+        @data["is_closed"] == true
+      end
+
+      # @return [Boolean]
+      def open?
+        !closed?
+      end
+
+      # Whether the thread hangs off a booking. Airbnb inquiries do not.
+      #
+      # @return [Boolean]
+      def booking?
+        !booking_id.nil?
+      end
+    end
+  end
+end

data/lib/channex/objects/occupancy.rb

@@ -0,0 +1,29 @@
+module Channex
+  module Objects
+    # Guest occupancy information
+    #
+    # @example
+    #   occupancy.adults       # => 2
+    #   occupancy.children     # => 1
+    #   occupancy.infants      # => 0
+    #   occupancy.total_guests # => 3
+    #
+    class Occupancy < Channex::Object
+      attribute :adults
+      attribute :children
+      attribute :infants
+
+      # Child ages array (when provided)
+      # @return [Array<Integer>]
+      def ages
+        @data["ages"] || []
+      end
+
+      # Total number of guests
+      # @return [Integer]
+      def total_guests
+        (adults || 0) + (children || 0) + (infants || 0)
+      end
+    end
+  end
+end

data/lib/channex/objects/review.rb

@@ -0,0 +1,87 @@
+module Channex
+  module Objects
+    # A guest's review of a stay, as Channex unifies it across Booking.com,
+    # Airbnb and Expedia.
+    #
+    # Like {MessageThread}, a review arrives as a JSON:API resource node;
+    # {.from_resource} flattens the identifier and relationships into the
+    # attributes so the whole review is one hash.
+    #
+    # Scores are out of 10 whatever the OTA rates on; `scores` holds one
+    # `{"category", "score"}` pair per category the OTA asks about, named in
+    # the OTA's own vocabulary (`clean` on Booking.com, `cleanliness` on Airbnb).
+    #
+    # @example
+    #   review.ota           # => "BookingCom"
+    #   review.overall_score # => 9.0
+    #   review.scores        # => [{"category" => "clean", "score" => 10}]
+    #   review.replied?      # => false
+    #
+    class Review < Channex::Object
+      attribute :id
+      attribute :content
+      attribute :guest_name
+      attribute :ota
+      attribute :ota_reservation_id
+      attribute :overall_score
+      attribute :reply
+      attribute :received_at
+      attribute :inserted_at
+      attribute :updated_at
+
+      # Lifted out of `relationships`
+      attribute :booking_id
+      attribute :channel_id
+      attribute :property_id
+
+      # Flatten a JSON:API resource node into a review
+      #
+      # @param node [Hash, nil] A `{"id", "attributes", "relationships"}` node
+      # @return [Review, nil]
+      def self.from_resource(node)
+        return nil if node.nil?
+
+        attributes = node["attributes"] || {}
+        relationships = node["relationships"] || {}
+
+        new(
+          attributes.merge(
+            "id" => node["id"],
+            "booking_id" => relationships.dig("booking", "data", "id"),
+            "channel_id" => relationships.dig("channel", "data", "id"),
+            "property_id" => relationships.dig("property", "data", "id")
+          ).compact
+        )
+      end
+
+      # Per-category scores, `{"category", "score"}` pairs
+      #
+      # @return [Array<Hash>]
+      def scores
+        @data["scores"] || []
+      end
+
+      # Review tag codes (Airbnb only)
+      #
+      # @return [Array<String>]
+      def tags
+        @data["tags"] || []
+      end
+
+      # Whether the property has replied
+      #
+      # @return [Boolean]
+      def replied?
+        @data["is_replied"] == true
+      end
+
+      # Whether Airbnb is holding the review back until the host reviews the
+      # guest in turn (Airbnb only)
+      #
+      # @return [Boolean]
+      def hidden?
+        @data["is_hidden"] == true
+      end
+    end
+  end
+end

data/lib/channex/objects/service.rb

@@ -0,0 +1,44 @@
+module Channex
+  module Objects
+    # Additional service, fee, or extra sold alongside a booking.
+    #
+    # Channex represents meals, fees, and extras uniformly in a booking's
+    # `services` array (present at both booking and room level), distinguished
+    # by `type`. A fee charged on a cancelled booking also arrives here — note
+    # that real OTA payloads use a specific `type` (e.g. Booking.com sends
+    # "Cancellation Fee"), not the generic "Fee" the API docs imply.
+    #
+    # `is_inclusive` indicates whether tax is already baked into the amount.
+    #
+    # @see https://docs.channex.io/api-v.1-documentation/bookings-collection
+    #
+    # @example
+    #   service.type           # => "Cancellation Fee"
+    #   service.name           # => "Cancellation Fee"
+    #   service.total_price    # => "12240.00" (total amount for the service)
+    #   service.price_per_unit # => "12240.00"
+    #   service.price_mode     # => "Per stay"
+    #   service.nights         # => 0
+    #   service.persons        # => 0
+    #   service.inclusive?     # => true
+    #   service.room_index     # => 0 (room the service is associated with, if any)
+    #
+    class Service < Channex::Object
+      attribute :type
+      attribute :name
+      attribute :total_price
+      attribute :price_per_unit
+      attribute :price_mode
+      attribute :persons
+      attribute :nights
+      attribute :room_index
+      attribute :inclusive, key: "is_inclusive"
+
+      # Whether tax is already included in the amount
+      # @return [Boolean]
+      def inclusive?
+        inclusive == true
+      end
+    end
+  end
+end

data/lib/channex/objects/tax.rb

@@ -0,0 +1,36 @@
+module Channex
+  module Objects
+    # Tax applied to a booking room.
+    #
+    # Channex represents taxes with the same shape as services: an amount
+    # (`total_price` / `price_per_unit`), a `price_mode`, and an `is_inclusive`
+    # flag indicating whether the tax is already baked into the room price.
+    #
+    # @see https://docs.channex.io/api-v.1-documentation/taxes-and-tax-sets
+    #
+    # @example
+    #   tax.type           # => "Value Added Tax (VAT)"
+    #   tax.name           # => "VAT (12%)"
+    #   tax.total_price    # => "1311.43"
+    #   tax.price_per_unit # => "1311.43"
+    #   tax.price_mode     # => "Per booking"
+    #   tax.inclusive?     # => true
+    #
+    class Tax < Channex::Object
+      attribute :type
+      attribute :name
+      attribute :total_price
+      attribute :price_per_unit
+      attribute :price_mode
+      attribute :persons
+      attribute :nights
+      attribute :inclusive, key: "is_inclusive"
+
+      # Whether the tax is already included in the price
+      # @return [Boolean]
+      def inclusive?
+        inclusive == true
+      end
+    end
+  end
+end

data/lib/channex/objects.rb

@@ -0,0 +1,22 @@
+module Channex
+  # Namespace for typed API response objects
+  #
+  # All objects inherit from Channex::Object and provide:
+  # - Typed attribute accessors
+  # - Hash compatibility via [], dig, to_h
+  # - Nested object wrapping
+  #
+  module Objects
+  end
+end
+
+# Load in dependency order (leaf nodes first)
+require_relative "objects/company"
+require_relative "objects/occupancy"
+require_relative "objects/guest"
+require_relative "objects/tax"
+require_relative "objects/service"
+require_relative "objects/guarantee"
+require_relative "objects/customer"
+require_relative "objects/booking_room"
+require_relative "objects/booking_revision"

data/lib/channex/resource.rb

@@ -0,0 +1,130 @@
+module Channex
+  # Base class for API resources
+  #
+  # Provides common CRUD operations and pagination support.
+  # Subclasses should define their resource path and customize
+  # behavior as needed.
+  #
+  class Resource
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+    end
+
+    # List all resources with optional filtering and pagination
+    #
+    # @param page [Integer] Page number (starts at 1)
+    # @param limit [Integer] Number of results per page (max 100)
+    # @param filter [Hash] Filter parameters
+    # @param order [Hash] Ordering parameters (e.g., { inserted_at: :asc })
+    # @param params [Hash] Keywords named by #filter_keys join the filter; the rest are sent as top-level params
+    # @return [Response]
+    def list(page: nil, limit: nil, filter: {}, order: {}, **params)
+      named_filters = params.extract!(*filter_keys).compact
+      filter = filter.merge(named_filters)
+      client.get(resource_path, params: query_params(page:, limit:, filter:, order:, **params))
+    end
+
+    # Retrieve all resources using automatic pagination
+    #
+    # @yield [data] Yields each page of data
+    # @yieldparam data [Array] Array of resource data from the page
+    # @return [Array] All resources if no block given
+    def list_all(filter: {}, order: {}, **params)
+      all_data = []
+      page = 1
+      limit = 100
+
+      loop do
+        response = list(page: page, limit: limit, filter: filter, order: order, **params)
+        data = response.data || []
+
+        if block_given?
+          yield data
+        else
+          all_data.concat(data)
+        end
+
+        break unless response.pagination.has_next?
+
+        page += 1
+      end
+
+      all_data unless block_given?
+    end
+
+    # Retrieve a single resource by ID
+    #
+    # @param id [String] Resource UUID
+    # @return [Response]
+    def retrieve(id)
+      client.get("#{resource_path}/#{id}")
+    end
+
+    # Create a new resource
+    #
+    # @param attributes [Hash] Resource attributes
+    # @return [Response]
+    def create(attributes)
+      client.post(resource_path, body: wrap_attributes(attributes))
+    end
+
+    # Update an existing resource
+    #
+    # @param id [String] Resource UUID
+    # @param attributes [Hash] Resource attributes to update
+    # @return [Response]
+    def update(id, attributes)
+      client.put("#{resource_path}/#{id}", body: wrap_attributes(attributes))
+    end
+
+    # Delete a resource
+    #
+    # @param id [String] Resource UUID
+    # @return [Response]
+    def delete(id)
+      client.delete("#{resource_path}/#{id}")
+    end
+
+    protected
+
+    # Build the query string Channex expects: pagination, filter and order are
+    # each nested one level deep (e.g. `pagination[page]=2`). Shared with
+    # resources whose collections hang off another resource's path.
+    #
+    # @return [Hash]
+    def query_params(page: nil, limit: nil, filter: {}, order: {}, **params)
+      query = params.dup
+
+      pagination = {}
+      pagination[:page] = page if page
+      pagination[:limit] = limit if limit
+      query[:pagination] = pagination unless pagination.empty?
+
+      query[:filter] = filter unless filter.empty?
+      query[:order] = order unless order.empty?
+
+      query
+    end
+
+    # Override in subclasses to define the API path
+    def resource_path
+      raise NotImplementedError, "Subclass must implement #resource_path"
+    end
+
+    # Override to change how attributes are wrapped for create/update
+    def wrap_attributes(attributes)
+      {resource_name => attributes}
+    end
+
+    def resource_name
+      self.class.name.demodulize.underscore.singularize
+    end
+
+    # Override to name the keywords #list sends to Channex as filters
+    def filter_keys
+      []
+    end
+  end
+end

data/lib/channex/resources/attachments.rb

@@ -0,0 +1,36 @@
+module Channex
+  module Resources
+    # Attachments API resource
+    #
+    # Sending a file to a guest is two calls: upload it here, then pass the
+    # returned id to {MessageThreads#send_message} or {Messages#send_message}.
+    #
+    # @example Send a photo of the directions
+    #   attachment = client.attachments.create(
+    #     file: Base64.strict_encode64(File.binread("directions.jpeg")),
+    #     file_name: "directions.jpeg",
+    #     file_type: "image/jpeg"
+    #   )
+    #   client.message_threads.send_message("thread-uuid", attachment_id: attachment.data["id"])
+    #
+    # @see https://docs.channex.io/api-v.1-documentation/messages-collection
+    #
+    class Attachments < Resource
+      # Upload an attachment
+      #
+      # @param file [String] Base64-encoded file contents
+      # @param file_name [String] File name, e.g. "photo.jpeg"
+      # @param file_type [String] MIME type, e.g. "image/jpeg"
+      # @return [Response]
+      def create(file:, file_name:, file_type:)
+        client.post(resource_path, body: {attachment: {file:, file_name:, file_type:}})
+      end
+
+      protected
+
+      def resource_path
+        "/attachments"
+      end
+    end
+  end
+end

data/lib/channex/resources/availability.rb

@@ -0,0 +1,87 @@
+module Channex
+  module Resources
+    # Availability API resource
+    #
+    # Availability represents how many rooms your property has to sell.
+    # This is the core data for inventory management in Channex.
+    #
+    # @example Get availability for a property
+    #   client.availability.list(
+    #     property_id: "property-uuid",
+    #     date_from: "2024-01-01",
+    #     date_to: "2024-01-31"
+    #   )
+    #
+    # @example Update availability for specific dates
+    #   client.availability.update([
+    #     {
+    #       property_id: "property-uuid",
+    #       room_type_id: "room-uuid",
+    #       date_from: "2024-01-15",
+    #       date_to: "2024-01-20",
+    #       availability: 5
+    #     }
+    #   ])
+    #
+    # @see https://docs.channex.io/api-v.1-documentation/ari
+    #
+    class Availability < Resource
+      # Get availability 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), uses filter[date][gte]
+      # @param date_to [String] End date (YYYY-MM-DD), uses filter[date][lte]
+      # @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 availability for properties
+      #
+      # Each value in the array should contain all required fields including property_id.
+      # You can update multiple properties and room types in a single request.
+      #
+      # @param values [Array<Hash>] Array of availability updates
+      #   Each hash should contain:
+      #   - property_id [String] Property UUID (required)
+      #   - room_type_id [String] Room Type UUID (required)
+      #   - date_from [String] Start date YYYY-MM-DD (required)
+      #   - date_to [String] End date YYYY-MM-DD (required)
+      #   - availability [Integer] Number of available rooms (required)
+      # @return [Response]
+      #
+      # @example Update availability for a date range
+      #   client.availability.update([
+      #     {
+      #       property_id: "716305c4-561a-4561-a187-7f5b8aeb5920",
+      #       room_type_id: "994d1375-dbbd-4072-8724-b2ab32ce781b",
+      #       date_from: "2024-01-15",
+      #       date_to: "2024-01-20",
+      #       availability: 5
+      #     }
+      #   ])
+      def update(values)
+        client.post(resource_path, body: {values: values})
+      end
+
+      protected
+
+      def resource_path
+        "/availability"
+      end
+    end
+  end
+end

data/lib/channex/resources/availability_rules.rb

@@ -0,0 +1,52 @@
+module Channex
+  module Resources
+    # Availability Rules API resource
+    #
+    # Availability Rules allow you to create dynamic rules that affect
+    # availability for specific channels, room types, and date ranges.
+    # Rules can close out availability, set offsets, or cap maximum availability.
+    #
+    # @example List availability rules for a property
+    #   client.availability_rules.list(property_id: "property-uuid")
+    #
+    # @example Create a close-out rule for specific dates
+    #   client.availability_rules.create(
+    #     property_id: "property-uuid",
+    #     affected_channels: ["channel-uuid"],
+    #     affected_room_types: ["room-type-uuid"],
+    #     type: "close_out",
+    #     start_date: "2024-12-24",
+    #     end_date: "2024-12-26"
+    #   )
+    #
+    # @example Create an availability offset rule
+    #   client.availability_rules.create(
+    #     property_id: "property-uuid",
+    #     affected_channels: ["channel-uuid"],
+    #     affected_room_types: ["room-type-uuid"],
+    #     type: "availability_offset",
+    #     value: 2,  # Reserve 2 rooms from OTA availability
+    #     start_date: "2024-01-01"
+    #   )
+    #
+    # @see https://docs.channex.io/api-v.1-documentation/availability-rules-collection
+    #
+    class AvailabilityRules < Resource
+      # Rule types
+      TYPES = %w[close_out availability_offset max_availability].freeze
+
+      # Days of week
+      DAYS = %w[mo tu we th fr sa su].freeze
+
+      protected
+
+      def resource_path
+        "/availability_rules"
+      end
+
+      def filter_keys
+        %i[property_id]
+      end
+    end
+  end
+end