channex 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 29c78c4808964bdee4372d293bcc895d30e521fdced531a03ce8690d2dbdf7a0
+  data.tar.gz: 025a53b3e8b4afe6b7545260166b9f11bd3d3daf0abb4beb36f1b21da9d07de7
+SHA512:
+  metadata.gz: 101bed4097f1783b0c36364bcbfcbfcc361ba4486ba0cf9cff6199c7a61d3b5f3134ac6b1b5c53061af676d8daa535f1a110af86e46a56d0dc8c3154bbf637f0
+  data.tar.gz: 33177e0c598657274ee3ca389d7ffba016b9232844cf71e8666048d202886693f3f510a2530af77f631ae2fd4ce91bf22f951a24dcdaf81005ff8c3228a508bd

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## [0.1.0](https://github.com/servos-app/channex/compare/channex-v0.1.0...channex/v0.1.0) (2026-11-11)
+
+
+### Features
+
+* extract Channex API client into standalone gem ([7d52d80](https://github.com/servos-app/channex/commit/7d52d80616a4b2cdb94a631446d1a903c612ba9c))
+* read and reply to guest reviews ([ce897c3](https://github.com/servos-app/channex/commit/ce897c390814e88f8cafbaa414c880a975aea23e))
+* read and reply to guest reviews ([96089ba](https://github.com/servos-app/channex/commit/96089bab7260731998beb53e72f69663c7eccd29))
+* sync the client with the copy in servos-app/servos ([0052022](https://github.com/servos-app/channex/commit/0052022ff14d6c27aa420d29b74168b390e72f25))
+
+
+### Bug Fixes
+
+* cancel a booking through the Booking CRS update endpoint ([2845c18](https://github.com/servos-app/channex/commit/2845c18e70d69a66ff83f3966d3333ad870621bd))
+
+
+### Miscellaneous Chores
+
+* release 0.1.0 ([1f54b4d](https://github.com/servos-app/channex/commit/1f54b4d45bfa3ff0029535b9990f3521a10f76aa))

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 asgerb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,281 @@
+# Channex
+
+A clean, idiomatic Ruby client for the [Channex.io](https://channex.io) channel
+manager API — properties, room types, rate plans, availability, restrictions,
+bookings, webhooks, and more.
+
+## Installation
+
+Add it to your `Gemfile`:
+
+```ruby
+gem "channex"
+```
+
+Then:
+
+```bash
+bundle install
+```
+
+Requires Ruby >= 3.2.
+
+## Configuration
+
+Configure globally once, typically in an initializer:
+
+```ruby
+Channex.configure do |config|
+  config.api_key     = ENV["CHANNEX_API_KEY"]
+  config.environment = :production   # :staging (default), :production,
+                                     # :secure_staging, :secure_production
+  config.timeout     = 30            # read timeout (seconds)
+  config.open_timeout = 10           # connection timeout (seconds)
+  config.logger      = Rails.logger  # optional; logs requests/responses at debug
+end
+
+client = Channex::Client.new
+```
+
+Or configure per-client, overriding the globals:
+
+```ruby
+client = Channex::Client.new(
+  api_key: "your-api-key",
+  environment: :staging
+)
+```
+
+## Usage
+
+### Resources
+
+Each resource is reachable from the client and exposes CRUD plus pagination:
+
+```ruby
+client.properties.list
+client.properties.retrieve("property-uuid")
+client.properties.create(title: "My Hotel", currency: "USD", ...)
+client.properties.update("property-uuid", title: "New Name")
+client.properties.delete("property-uuid")
+```
+
+Available resources: `properties`, `room_types`, `rate_plans`, `availability`,
+`restrictions`, `bookings`, `booking_revisions`, `channels`, `webhooks`,
+`taxes`, `tax_sets`, `photos`, `groups`, `group_users`, `property_users`,
+`facilities`, `messages`, `message_threads`, `reviews`, `attachments`, `hotel_policies`,
+`availability_rules`.
+
+### Pagination
+
+```ruby
+# One page
+response = client.properties.list(page: 1, limit: 50)
+response.data
+response.pagination.has_next?
+
+# Every page, collected
+all = client.properties.list_all
+
+# Every page, streamed (avoids loading everything into memory)
+client.properties.list_all do |page|
+  page.each { |property| process(property) }
+end
+```
+
+### Filtering and ordering
+
+```ruby
+client.bookings.list(
+  property_id: "property-uuid",
+  status: "new",
+  date_from: "2024-01-01",
+  date_to: "2024-01-31",
+  order: { inserted_at: :asc }
+)
+```
+
+### Availability & Restrictions (ARI)
+
+Read by property and date range; write in bulk:
+
+```ruby
+client.availability.list(
+  property_id: "property-uuid",
+  date_from: "2024-01-01",
+  date_to: "2024-01-31"
+)
+
+client.availability.update([
+  {
+    property_id: "property-uuid",
+    room_type_id: "room-uuid",
+    date_from: "2024-01-15",
+    date_to: "2024-01-20",
+    availability: 5
+  }
+])
+
+client.restrictions.update([
+  {
+    property_id: "property-uuid",
+    rate_plan_id: "rate-plan-uuid",
+    date_from: "2024-01-15",
+    date_to: "2024-01-20",
+    rate: 30000,
+    min_stay_arrival: 2,
+    closed_to_arrival: false,
+    stop_sell: false
+  }
+])
+```
+
+### Receiving bookings
+
+New bookings arrive through the booking revisions feed. **You must acknowledge
+each revision after processing** — unacknowledged revisions are re-served for 30
+minutes and then trigger email warnings.
+
+```ruby
+response = client.booking_revisions.feed
+
+response.objects.each do |revision|   # typed Channex::Objects::BookingRevision
+  puts revision.customer.full_name
+  puts revision.check_in_date         # Date
+  revision.rooms.each { |room| puts room.nights }
+
+  client.booking_revisions.acknowledge(revision.id)
+end
+```
+
+Raw hash access is available via `response.data` if you prefer.
+
+### Guest messages
+
+Channex unifies the guest inboxes of Booking.com, Airbnb and Expedia behind one
+API. A **message thread** is one conversation; threads are the channel-agnostic
+entry point because they also cover conversations with no booking behind them —
+an Airbnb inquiry is a thread about a stay that does not exist yet.
+
+```ruby
+threads = client.message_threads.list(property_id: "property-uuid")
+thread = Channex::Objects::MessageThread.from_resource(threads.data.first)
+
+thread.title          # => "Maldonado Roxy"
+thread.provider       # => "BookingCom"
+thread.booking_id     # => nil for an Airbnb inquiry
+thread.last_message   # => Channex::Objects::Message
+
+messages = client.message_threads.messages(thread.id, order: {inserted_at: :asc})
+messages.data.map { |node| Channex::Objects::Message.from_resource(node) }
+        .each { |message| puts "#{message.sender}: #{message.message}" }
+
+client.message_threads.send_message(thread.id, message: "Check-in is from 15:00.")
+```
+
+The same conversation is reachable from the booking it belongs to:
+
+```ruby
+client.messages.list(booking_id: "booking-uuid")
+client.messages.send_message(booking_id: "booking-uuid", message: "See you soon!")
+```
+
+Sending a file is two calls — upload, then send the returned id:
+
+```ruby
+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.id, attachment_id: attachment.data["id"])
+```
+
+Two thread actions round out the inbox: `close(id)` archives a thread, and
+`no_reply_needed(id)` tells Booking.com a guest message needs no answer so its
+response-time score stays honest.
+
+Every call here needs the Messages application installed on the property,
+otherwise Channex answers `403 Forbidden`. Bookings from an OTA without a
+messaging API answer `422 Unprocessable Entity` (`not_supported`).
+
+### Guest reviews
+
+Reviews from Booking.com, Airbnb and Expedia come through the same Messages &
+Reviews application, so they answer `403 Forbidden` without it too. Scores are
+out of 10 whatever the OTA rates on, and categories keep the OTA's own names.
+
+```ruby
+reviews = client.reviews.list(property_id: "property-uuid")
+review = Channex::Objects::Review.from_resource(reviews.data.first)
+
+review.ota            # => "BookingCom"
+review.overall_score  # => 9.0
+review.scores         # => [{"category" => "clean", "score" => 10}, ...]
+review.booking_id     # => the Channex booking the review is about
+review.replied?       # => false
+
+client.reviews.reply(review.id, reply: "Thank you for staying with us.")
+```
+
+### Typed objects
+
+Booking data is wrapped in typed objects that still behave like hashes:
+
+```ruby
+revision.status          # typed accessor
+revision.new?            # => true
+revision["booking_id"]   # hash access
+revision.dig("customer", "mail")
+revision.to_h            # underlying hash
+```
+
+## Error handling
+
+All errors inherit from `Channex::Errors::Error` and carry `#code` and
+`#response`:
+
+```ruby
+begin
+  client.properties.retrieve("missing-uuid")
+rescue Channex::Errors::NotFoundError => e
+  e.code      # => 404
+rescue Channex::Errors::ValidationError => e
+  e.errors    # => [...] validation details
+rescue Channex::Errors::RateLimitError => e
+  e.retry_after
+rescue Channex::Errors::Error => e
+  e.response
+end
+```
+
+| Status | Error class            |
+| ------ | ---------------------- |
+| 401    | `AuthenticationError`  |
+| 403    | `ForbiddenError`       |
+| 404    | `NotFoundError`        |
+| 422    | `ValidationError`      |
+| 429    | `RateLimitError`       |
+| 5xx    | `ServerError`          |
+| —      | `ConnectionError`, `TimeoutError`, `ConfigurationError` |
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Run the
+test suite with:
+
+```bash
+bundle exec rake test
+```
+
+Or `bin/console` for an interactive prompt.
+
+Class loading uses [Zeitwerk](https://github.com/fxn/zeitwerk): files under
+`lib/channex/` are autoloaded by convention (file path mirrors constant name),
+so no manual `require` statements are needed when adding new resources or
+objects.
+
+## License
+
+MIT.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: %i[test]

data/lib/channex/client.rb

@@ -0,0 +1,283 @@
+module Channex
+  # Main client for interacting with the Channex API
+  #
+  # @example Basic usage
+  #   client = Channex::Client.new(api_key: "your-api-key")
+  #   client.properties.list
+  #
+  # @example With environment override
+  #   client = Channex::Client.new(
+  #     api_key: "your-api-key",
+  #     environment: :production
+  #   )
+  #
+  class Client
+    attr_reader :api_key, :configuration
+
+    def initialize(api_key: nil, environment: nil, timeout: nil, open_timeout: nil)
+      @configuration = Configuration.new
+      @configuration.api_key = api_key || Channex.configuration.api_key
+      @configuration.environment = environment || Channex.configuration.environment
+      @configuration.timeout = timeout || Channex.configuration.timeout
+      @configuration.open_timeout = open_timeout || Channex.configuration.open_timeout
+      @configuration.logger = Channex.configuration.logger
+
+      @api_key = @configuration.api_key
+
+      validate_configuration!
+    end
+
+    # Resource accessors
+
+    def properties
+      @properties ||= Resources::Properties.new(self)
+    end
+
+    def room_types
+      @room_types ||= Resources::RoomTypes.new(self)
+    end
+
+    def rate_plans
+      @rate_plans ||= Resources::RatePlans.new(self)
+    end
+
+    def availability
+      @availability ||= Resources::Availability.new(self)
+    end
+
+    def restrictions
+      @restrictions ||= Resources::Restrictions.new(self)
+    end
+
+    def bookings
+      @bookings ||= Resources::Bookings.new(self)
+    end
+
+    def booking_revisions
+      @booking_revisions ||= Resources::BookingRevisions.new(self)
+    end
+
+    def channels
+      @channels ||= Resources::Channels.new(self)
+    end
+
+    def webhooks
+      @webhooks ||= Resources::Webhooks.new(self)
+    end
+
+    def taxes
+      @taxes ||= Resources::Taxes.new(self)
+    end
+
+    def tax_sets
+      @tax_sets ||= Resources::TaxSets.new(self)
+    end
+
+    def photos
+      @photos ||= Resources::Photos.new(self)
+    end
+
+    def groups
+      @groups ||= Resources::Groups.new(self)
+    end
+
+    def group_users
+      @group_users ||= Resources::GroupUsers.new(self)
+    end
+
+    def property_users
+      @property_users ||= Resources::PropertyUsers.new(self)
+    end
+
+    def facilities
+      @facilities ||= Resources::Facilities.new(self)
+    end
+
+    def messages
+      @messages ||= Resources::Messages.new(self)
+    end
+
+    def message_threads
+      @message_threads ||= Resources::MessageThreads.new(self)
+    end
+
+    def reviews
+      @reviews ||= Resources::Reviews.new(self)
+    end
+
+    def attachments
+      @attachments ||= Resources::Attachments.new(self)
+    end
+
+    def hotel_policies
+      @hotel_policies ||= Resources::HotelPolicies.new(self)
+    end
+
+    def availability_rules
+      @availability_rules ||= Resources::AvailabilityRules.new(self)
+    end
+
+    # HTTP methods
+
+    def get(path, params: {})
+      request(:get, path, params: params)
+    end
+
+    def post(path, body: {})
+      request(:post, path, body: body)
+    end
+
+    def put(path, body: {})
+      request(:put, path, body: body)
+    end
+
+    def delete(path)
+      request(:delete, path)
+    end
+
+    private
+
+    def validate_configuration!
+      if @api_key.nil? || @api_key.empty?
+        raise Errors::ConfigurationError, "API key is required. Set via Channex.configure or pass to Client.new"
+      end
+    end
+
+    def request(method, path, params: {}, body: nil)
+      uri = build_uri(path, params)
+      http = build_http(uri)
+      request = build_request(method, uri, body)
+
+      log_request(method, uri, body)
+
+      response = execute_request(http, request)
+      channex_response = Response.new(response)
+
+      log_response(channex_response)
+      handle_errors(channex_response)
+
+      channex_response
+    rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, SocketError => e
+      raise Errors::ConnectionError.new("Connection failed: #{e.message}")
+    rescue Net::OpenTimeout
+      raise Errors::TimeoutError.new("Connection timed out")
+    rescue Net::ReadTimeout
+      raise Errors::TimeoutError.new("Request timed out")
+    end
+
+    def build_uri(path, params)
+      url = "#{configuration.api_url}#{path}"
+      url += "/" unless url.end_with?("/")
+
+      uri = URI(url)
+      uri.query = URI.encode_www_form(flatten_params(params)) unless params.empty?
+      uri
+    end
+
+    def build_http(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.read_timeout = configuration.timeout
+      http.open_timeout = configuration.open_timeout
+      http
+    end
+
+    def build_request(method, uri, body)
+      request_class = {
+        get: Net::HTTP::Get,
+        post: Net::HTTP::Post,
+        put: Net::HTTP::Put,
+        delete: Net::HTTP::Delete
+      }.fetch(method)
+
+      request = request_class.new(uri)
+      request["Content-Type"] = "application/json"
+      request["Accept"] = "application/json"
+      request["user-api-key"] = api_key
+      request.body = body.to_json if body.present?
+
+      request
+    end
+
+    def execute_request(http, request)
+      http.request(request)
+    end
+
+    def flatten_params(params, prefix = nil)
+      params.each_with_object([]) do |(key, value), result|
+        prefixed_key = prefix ? "#{prefix}[#{key}]" : key.to_s
+
+        case value
+        when Hash
+          result.concat(flatten_params(value, prefixed_key))
+        when Array
+          value.each { |v| result << ["#{prefixed_key}[]", v.to_s] }
+        else
+          result << [prefixed_key, value.to_s]
+        end
+      end
+    end
+
+    def handle_errors(response)
+      return if response.success?
+
+      error_message = extract_error_message(response)
+
+      case response.status
+      when 401
+        raise Errors::AuthenticationError.new(error_message, response: response, code: 401)
+      when 403
+        raise Errors::ForbiddenError.new(error_message, response: response, code: 403)
+      when 404
+        raise Errors::NotFoundError.new(error_message, response: response, code: 404)
+      when 422
+        raise Errors::ValidationError.new(
+          error_message,
+          errors: (response.error["details"] if response.error.is_a?(Hash)) || {},
+          response: response,
+          code: 422
+        )
+      when 429
+        retry_after = response.headers["retry-after"]&.first&.to_i
+        raise Errors::RateLimitError.new(
+          error_message,
+          retry_after: retry_after,
+          response: response,
+          code: 429
+        )
+      when 500..599
+        raise Errors::ServerError.new(error_message, response: response, code: response.status)
+      else
+        raise Errors::Error.new(error_message, response: response, code: response.status)
+      end
+    end
+
+    def extract_error_message(response)
+      error = response.error
+      if error.is_a?(Hash)
+        # Handle both error formats:
+        # - { "message": "..." } or { "error": "..." }
+        # - { "code": "...", "title": "..." }
+        error["message"] || error["title"] || error["error"] || error.to_s
+      elsif error.is_a?(String)
+        error
+      else
+        "HTTP #{response.status}"
+      end
+    end
+
+    def log_request(method, uri, body)
+      return unless configuration.logger
+
+      configuration.logger.debug "[Channex] #{method.upcase} #{uri}"
+      configuration.logger.debug "[Channex] Body: #{body.to_json}" if body
+    end
+
+    def log_response(response)
+      return unless configuration.logger
+
+      configuration.logger.debug "[Channex] Response: #{response.status}"
+      configuration.logger.debug "[Channex] Body: #{response.raw_body}" if response.raw_body
+    end
+  end
+end

data/lib/channex/configuration.rb

@@ -0,0 +1,52 @@
+module Channex
+  # Configuration for the Channex client
+  #
+  # @example
+  #   Channex.configure do |config|
+  #     config.api_key = "your-api-key"
+  #     config.environment = :production
+  #     config.timeout = 30
+  #   end
+  #
+  class Configuration
+    ENVIRONMENTS = {
+      staging: "https://staging.channex.io",
+      production: "https://app.channex.io",
+      secure_staging: "https://secure-staging.channex.io",
+      secure_production: "https://secure.channex.io"
+    }.freeze
+
+    attr_accessor :api_key, :timeout, :open_timeout, :logger
+    attr_reader :environment
+
+    def initialize
+      @api_key = nil
+      @environment = :staging
+      @timeout = 30
+      @open_timeout = 10
+      @logger = nil
+    end
+
+    def environment=(env)
+      env = env.to_sym
+      unless ENVIRONMENTS.key?(env)
+        raise ArgumentError, "Invalid environment: #{env}. Valid options: #{ENVIRONMENTS.keys.join(", ")}"
+      end
+
+      @environment = env
+    end
+
+    def base_url
+      ENVIRONMENTS.fetch(@environment)
+    end
+
+    def api_url
+      "#{base_url}/api/v1"
+    end
+
+    def secure_api_url
+      secure_env = (@environment == :production) ? :secure_production : :secure_staging
+      "#{ENVIRONMENTS.fetch(secure_env)}/api/v1"
+    end
+  end
+end