channex 0.1.0

data/lib/channex/resources/booking_revisions.rb

@@ -0,0 +1,112 @@
+module Channex
+  module Resources
+    # Booking Revisions API resource
+    #
+    # Booking Revisions are snapshots of bookings at a given time.
+    # Each time an OTA provides an update, a new revision is created.
+    # The feed endpoint is the primary way to receive new bookings from Channex.
+    #
+    # IMPORTANT: You must acknowledge bookings after processing them.
+    # Not acknowledging bookings will result in them being repeatedly
+    # returned for 30 minutes, followed by email warnings.
+    #
+    # @example Get unacknowledged booking revisions (typed objects)
+    #   response = client.booking_revisions.feed
+    #   response.objects.each do |revision|
+    #     puts revision.customer.full_name
+    #     revision.rooms.each { |room| puts room.nights }
+    #     client.booking_revisions.acknowledge(revision.id)
+    #   end
+    #
+    # @example Hash access still works for backwards compatibility
+    #   response = client.booking_revisions.feed
+    #   response.data.each do |revision|
+    #     puts revision["attributes"]["customer"]["name"]
+    #   end
+    #
+    # @see https://docs.channex.io/api-v.1-documentation/bookings-collection
+    #
+    class BookingRevisions < Resource
+      # Get unacknowledged booking revisions from the feed
+      #
+      # Returns a response with both raw data and typed objects.
+      # Use response.objects for typed access, response.data for raw hashes.
+      #
+      # @param order [Hash] Ordering options (e.g., { inserted_at: :asc })
+      # @return [Response] Response with #objects method for typed access
+      def feed(order: {inserted_at: :asc})
+        response = client.get("#{resource_path}/feed", params: {order: order})
+        add_objects_wrapper(response)
+        response
+      end
+
+      # Acknowledge a booking revision
+      #
+      # Once acknowledged, the revision will not appear in the feed again.
+      #
+      # @param id [String] Booking revision UUID
+      # @return [Response]
+      def acknowledge(id)
+        client.post("#{resource_path}/#{id}/ack", body: {})
+      end
+
+      # Acknowledge multiple booking revisions at once
+      #
+      # @param ids [Array<String>] Array of booking revision UUIDs
+      # @return [Array<Response>]
+      def acknowledge_all(ids)
+        ids.map { |id| acknowledge(id) }
+      end
+
+      # Retrieve a single booking revision
+      #
+      # Returns a response with both raw data and a typed object.
+      # Use response.object for typed access, response.data for raw hash.
+      #
+      # @param id [String] Booking revision UUID
+      # @return [Response] Response with #object method for typed access
+      def retrieve(id)
+        response = super
+        add_object_wrapper(response)
+        response
+      end
+
+      # List booking revisions, filtered by booking_id
+      #
+      # @return [Response] Response with #objects method for typed access
+      def list(**)
+        response = super
+        add_objects_wrapper(response)
+        response
+      end
+
+      protected
+
+      def resource_path
+        "/booking_revisions"
+      end
+
+      def filter_keys
+        %i[booking_id]
+      end
+
+      private
+
+      # Add #object method to response for single revision
+      def add_object_wrapper(response)
+        response.define_singleton_method(:object) do
+          @_object ||= Channex::Objects::BookingRevision.construct_from(data&.dig("attributes"))
+        end
+      end
+
+      # Add #objects method to response for multiple revisions
+      def add_objects_wrapper(response)
+        response.define_singleton_method(:objects) do
+          @_objects ||= (data || []).map do |item|
+            Channex::Objects::BookingRevision.construct_from(item["attributes"])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/channex/resources/bookings.rb

@@ -0,0 +1,72 @@
+module Channex
+  module Resources
+    # Bookings API resource
+    #
+    # Bookings represent reservations made through channels connected to Channex.
+    # For receiving new bookings, use the BookingRevisions resource with the feed endpoint.
+    #
+    # @example List bookings
+    #   client.bookings.list(property_id: "property-uuid")
+    #
+    # @example Retrieve a booking
+    #   client.bookings.retrieve("booking-uuid")
+    #
+    # @example Create a booking (requires Booking CRS App)
+    #   client.bookings.create(
+    #     property_id: "property-uuid",
+    #     rooms: [{
+    #       room_type_id: "room-type-uuid",
+    #       rate_plan_id: "rate-plan-uuid",
+    #       checkin_date: "2024-02-01",
+    #       checkout_date: "2024-02-05",
+    #       guests: [{ name: "John Doe" }]
+    #     }]
+    #   )
+    #
+    # @see https://docs.channex.io/api-v.1-documentation/bookings-collection
+    # @see https://docs.channex.io/api-v.1-documentation/booking-crs-api
+    #
+    class Bookings < Resource
+      # List bookings; date_from and date_to bound the arrival date
+      #
+      # @return [Response]
+      def list(date_from: nil, date_to: nil, filter: {}, **options)
+        arrival_date = {gte: date_from, lte: date_to}.compact
+        filter = filter.merge(arrival_date:) if arrival_date.any?
+        super(filter:, **options)
+      end
+
+      # Revise (modify) an existing booking
+      #
+      # @param reservation_id [String] The reservation ID (part after "-" in unique_id)
+      # @param attributes [Hash] Updated booking attributes with status: "modified"
+      # @return [Response]
+      def revise(reservation_id, attributes)
+        client.post(
+          "#{resource_path}/revise",
+          body: {
+            booking: attributes.merge(reservation_id: reservation_id, status: "modified")
+          }
+        )
+      end
+
+      # Cancel a booking, including one that came from an OTA (requires Booking CRS App)
+      #
+      # @param booking_id [String] The booking UUID
+      # @return [Response]
+      def cancel(booking_id)
+        update(booking_id, status: "cancelled")
+      end
+
+      protected
+
+      def resource_path
+        "/bookings"
+      end
+
+      def filter_keys
+        %i[property_id channel_id status]
+      end
+    end
+  end
+end

data/lib/channex/resources/channels.rb

@@ -0,0 +1,96 @@
+module Channex
+  module Resources
+    # Channels API resource
+    #
+    # Channels represent connections to OTAs (Online Travel Agencies) like
+    # Booking.com, Airbnb, Expedia, etc.
+    #
+    # @example List channels for a property
+    #   client.channels.list(property_id: "property-uuid")
+    #
+    # @example Retrieve a channel
+    #   client.channels.retrieve("channel-uuid")
+    #
+    # @see https://docs.channex.io/api-v.1-documentation/channel-api
+    #
+    class Channels < Resource
+      # Get list of available channel codes/types
+      #
+      # @return [Response]
+      def codes
+        client.get("/channel_codes")
+      end
+
+      # Test OTA credentials before connecting. Returns the OTA's acknowledgement
+      # that the hotel_id + channel are reachable. The first call also reveals
+      # whether the account has Channel API access.
+      #
+      # @param channel [String] OTA code (e.g. "BookingCom")
+      # @param settings [Hash] OTA settings, at least { hotel_id: "..." }
+      # @return [Response]
+      def test_connection(channel:, settings:)
+        client.post("#{resource_path}/test_connection", body: {channel:, settings:})
+      end
+
+      # Fetch the OTA's rooms and rates to map against local rate plans. For
+      # Booking.com this returns rooms[].rates[], each keyed by an integer code.
+      #
+      # @param channel [String] OTA code (e.g. "BookingCom")
+      # @param settings [Hash] OTA settings, at least { hotel_id: "..." }
+      # @return [Response]
+      def mapping_details(channel:, settings:)
+        client.post("#{resource_path}/mapping_details", body: {channel:, settings:})
+      end
+
+      # Connect a new channel to a property
+      #
+      # @param attributes [Hash] Channel attributes including property_id, channel code, credentials
+      # @return [Response]
+      def connect(attributes)
+        create(attributes)
+      end
+
+      # Channels are created inactive; activate to go live.
+      #
+      # @param id [String] Channel UUID
+      # @return [Response]
+      def activate(id)
+        client.post("#{resource_path}/#{id}/activate", body: {})
+      end
+
+      # Pause a live channel without deleting it.
+      #
+      # @param id [String] Channel UUID
+      # @return [Response]
+      def deactivate(id)
+        client.post("#{resource_path}/#{id}/deactivate", body: {})
+      end
+
+      # Disconnect a channel (must be inactive first)
+      #
+      # @param id [String] Channel UUID
+      # @return [Response]
+      def disconnect(id)
+        delete(id)
+      end
+
+      # Full sync a channel (refresh all data from OTA)
+      #
+      # @param id [String] Channel UUID
+      # @return [Response]
+      def full_sync(id)
+        client.post("#{resource_path}/#{id}/full_sync", body: {})
+      end
+
+      protected
+
+      def resource_path
+        "/channels"
+      end
+
+      def filter_keys
+        %i[property_id]
+      end
+    end
+  end
+end

data/lib/channex/resources/facilities.rb

@@ -0,0 +1,29 @@
+module Channex
+  module Resources
+    # Facilities API resource
+    #
+    # Facilities represent amenities available at properties or room types.
+    # This is a read-only resource providing the list of available facility IDs.
+    #
+    # @example List available facilities
+    #   client.facilities.list
+    #
+    # @see https://docs.channex.io/api-v.1-documentation/facilities-collection
+    #
+    class Facilities < Resource
+      # List available facilities
+      #
+      # @param options [Hash] Additional options
+      # @return [Response]
+      def list(**options)
+        client.get(resource_path, params: options)
+      end
+
+      protected
+
+      def resource_path
+        "/facilities"
+      end
+    end
+  end
+end

data/lib/channex/resources/group_users.rb

@@ -0,0 +1,76 @@
+module Channex
+  module Resources
+    # Group Users API resource
+    #
+    # Group Users represent the association between users and groups,
+    # defining access permissions. By inviting a User into a Group, you
+    # automatically grant access for this user to all properties in the Group.
+    #
+    # @example List users in a group
+    #   client.group_users.list(group_id: "group-uuid")
+    #
+    # @example Invite a user to a group
+    #   client.group_users.invite(
+    #     group_id: "group-uuid",
+    #     user_email: "user@example.com",
+    #     role: "user"
+    #   )
+    #
+    # @see https://docs.channex.io/api-v.1-documentation/group-users-collection
+    #
+    class GroupUsers < Resource
+      ROLES = %w[owner user].freeze
+
+      # Invite a user to a group
+      #
+      # If the user is not registered, Channex will create their account
+      # automatically and send an email with instructions to onboard.
+      #
+      # @param group_id [String] Group UUID (required)
+      # @param user_email [String] Email address of the user to invite (required)
+      # @param role [String] Role: "owner" or "user" (required)
+      # @param overrides [Hash] Access policies overrides (optional)
+      # @return [Response]
+      #
+      # @example Invite a user with default permissions
+      #   client.group_users.invite(
+      #     group_id: "52397a6e-c330-44f4-a293-47042d3a3607",
+      #     user_email: "other_user@channex.io",
+      #     role: "user"
+      #   )
+      def invite(group_id:, user_email:, role:, overrides: {})
+        client.post(resource_path, body: {
+          invite: {
+            group_id: group_id,
+            user_email: user_email,
+            role: role,
+            overrides: overrides
+          }
+        })
+      end
+
+      # @see #invite
+      def create(attributes)
+        invite(**attributes)
+      end
+
+      # Revoke a user's access to a group
+      #
+      # @param id [String] Group User UUID
+      # @return [Response]
+      def revoke(id)
+        delete(id)
+      end
+
+      protected
+
+      def resource_path
+        "/group_users"
+      end
+
+      def filter_keys
+        %i[group_id]
+      end
+    end
+  end
+end

data/lib/channex/resources/groups.rb

@@ -0,0 +1,26 @@
+module Channex
+  module Resources
+    # Groups API resource
+    #
+    # Groups are used to organize properties and control access.
+    # Each property can have a Base Group assigned.
+    #
+    # @example List groups
+    #   client.groups.list
+    #
+    # @example Create a group
+    #   client.groups.create(
+    #     title: "Europe Hotels"
+    #   )
+    #
+    # @see https://docs.channex.io/api-v.1-documentation/groups-collection
+    #
+    class Groups < Resource
+      protected
+
+      def resource_path
+        "/groups"
+      end
+    end
+  end
+end

data/lib/channex/resources/hotel_policies.rb

@@ -0,0 +1,54 @@
+module Channex
+  module Resources
+    # Hotel Policies API resource
+    #
+    # Hotel Policies contain property-level settings like check-in/check-out times,
+    # internet access, parking, pets policy, and smoking rules.
+    #
+    # @example List hotel policies for a property
+    #   client.hotel_policies.list(property_id: "property-uuid")
+    #
+    # @example Create a hotel policy
+    #   client.hotel_policies.create(
+    #     property_id: "property-uuid",
+    #     title: "Standard Policy",
+    #     currency: "USD",
+    #     checkin_time: "15:00",
+    #     checkout_time: "11:00",
+    #     pets_policy: "not_allowed",
+    #     smoking_policy: "no_smoking"
+    #   )
+    #
+    # @see https://docs.channex.io/api-v.1-documentation/hotel-policy-collection
+    #
+    class HotelPolicies < Resource
+      # Pets policy options
+      PETS_POLICIES = %w[allowed not_allowed by_arrangements pets_not_allowed_on_beds].freeze
+
+      # Smoking policy options
+      SMOKING_POLICIES = %w[no_smoking smoking_allowed designated_areas].freeze
+
+      # Internet access type options
+      INTERNET_ACCESS_TYPES = %w[wifi wired none].freeze
+
+      # Internet access coverage options
+      INTERNET_ACCESS_COVERAGES = %w[entire_property public_areas some_rooms all_rooms].freeze
+
+      # Parking type options
+      PARKING_TYPES = %w[on_site off_site none].freeze
+
+      # Parking reservation options
+      PARKING_RESERVATIONS = %w[needed not_needed not_available].freeze
+
+      protected
+
+      def resource_path
+        "/hotel_policies"
+      end
+
+      def filter_keys
+        %i[property_id]
+      end
+    end
+  end
+end

data/lib/channex/resources/message_threads.rb

@@ -0,0 +1,89 @@
+module Channex
+  module Resources
+    # Message Threads API resource
+    #
+    # A message thread is one guest conversation, normalised by Channex across
+    # Booking.com, Airbnb and Expedia. Threads are the channel-agnostic entry
+    # point: they exist even when there is no booking to hang them off (an
+    # Airbnb inquiry), which booking-scoped messages cannot represent.
+    #
+    # Requires the Messages application to be installed on the property —
+    # without it every call in here answers 403 Forbidden.
+    #
+    # @example List the open threads for a property
+    #   client.message_threads.list(property_id: "property-uuid")
+    #
+    # @example Read a conversation
+    #   client.message_threads.messages("thread-uuid", order: {inserted_at: :asc})
+    #
+    # @example Reply to the guest
+    #   client.message_threads.send_message("thread-uuid", message: "Check-in is from 15:00.")
+    #
+    # @see https://docs.channex.io/api-v.1-documentation/messages-collection
+    #
+    class MessageThreads < Resource
+      # List the messages on a thread, newest first by default
+      #
+      # @param id [String] Thread UUID
+      # @param options [Hash] Additional options (page, limit, filter, order)
+      # @return [Response]
+      def messages(id, **options)
+        client.get("#{resource_path}/#{id}/messages", params: query_params(**options))
+      end
+
+      # Send a message to the guest on a thread
+      #
+      # Pass `attachment_id` to send a file previously uploaded through
+      # {Attachments#create}; `message` and `attachment_id` can be combined to
+      # send a file with a caption.
+      #
+      # @param id [String] Thread UUID
+      # @param message [String] Message text
+      # @param attachment_id [String] Attachment UUID from {Attachments#create}
+      # @param attributes [Hash] Additional message attributes
+      # @return [Response]
+      def send_message(id, message: nil, attachment_id: nil, **attributes)
+        client.post(
+          "#{resource_path}/#{id}/messages",
+          body: {message: message_attributes(message:, attachment_id:, **attributes)}
+        )
+      end
+
+      # Close a thread
+      #
+      # @param id [String] Thread UUID
+      # @return [Response]
+      def close(id)
+        client.post("#{resource_path}/#{id}/close", body: {})
+      end
+
+      # Mark a thread as needing no reply (Booking.com only)
+      #
+      # Booking.com scores properties on how fast they answer, but some guest
+      # messages do not call for an answer at all. Marking the thread keeps the
+      # response-time score honest instead of leaving the clock running.
+      #
+      # @param id [String] Thread UUID
+      # @return [Response]
+      def no_reply_needed(id)
+        client.post("#{resource_path}/#{id}/no_reply_needed", body: {})
+      end
+
+      protected
+
+      def resource_path
+        "/message_threads"
+      end
+
+      def filter_keys
+        %i[property_id booking_id]
+      end
+
+      def message_attributes(message: nil, attachment_id: nil, **attributes)
+        attributes[:message] = message if message
+        attributes[:attachment_id] = attachment_id if attachment_id
+        attributes
+      end
+    end
+  end
+end

data/lib/channex/resources/messages.rb

@@ -0,0 +1,64 @@
+module Channex
+  module Resources
+    # Booking Messages API resource
+    #
+    # The booking-scoped view of the same conversations {MessageThreads}
+    # exposes: reach a guest by the booking you already hold, without first
+    # resolving which thread it belongs to. Channex answers 422 `not_supported`
+    # for bookings from an OTA that has no messaging API.
+    #
+    # Requires the Messages application to be installed on the property.
+    #
+    # @example Read the conversation on a booking
+    #   client.messages.list(booking_id: "booking-uuid")
+    #
+    # @example Answer the guest
+    #   client.messages.send_message(
+    #     booking_id: "booking-uuid",
+    #     message: "Thank you for your reservation!"
+    #   )
+    #
+    # @see https://docs.channex.io/api-v.1-documentation/messages-collection
+    #
+    class Messages < Resource
+      # List the messages on a booking, newest first by default
+      #
+      # @param booking_id [String] Booking UUID
+      # @param options [Hash] Additional options (page, limit, filter, order)
+      # @return [Response]
+      def list(booking_id:, **options)
+        client.get(booking_path(booking_id), params: query_params(**options))
+      end
+
+      # Send a message to the guest on a booking
+      #
+      # Pass `attachment_id` to send a file previously uploaded through
+      # {Attachments#create}; `message` and `attachment_id` can be combined to
+      # send a file with a caption.
+      #
+      # @param booking_id [String] Booking UUID
+      # @param message [String] Message text
+      # @param attachment_id [String] Attachment UUID from {Attachments#create}
+      # @param attributes [Hash] Additional message attributes
+      # @return [Response]
+      def send_message(booking_id:, message: nil, attachment_id: nil, **attributes)
+        attributes[:message] = message if message
+        attributes[:attachment_id] = attachment_id if attachment_id
+
+        client.post(booking_path(booking_id), body: {message: attributes})
+      end
+
+      protected
+
+      # Messages only exist under a booking, so there is no collection of their
+      # own to retrieve, update or delete.
+      def resource_path
+        raise NotImplementedError, "Messages are scoped to a booking — use #list or #send_message"
+      end
+
+      def booking_path(booking_id)
+        "/bookings/#{booking_id}/messages"
+      end
+    end
+  end
+end