channex 0.1.0

data/lib/channex/errors.rb

@@ -0,0 +1,62 @@
+module Channex
+  # Error classes for Channex API responses
+  module Errors
+    # Base error class for all Channex errors
+    class Error < StandardError
+      attr_reader :response, :code
+
+      def initialize(message = nil, response: nil, code: nil)
+        @response = response
+        @code = code
+        super(message)
+      end
+    end
+
+    # Raised when authentication fails (401)
+    class AuthenticationError < Error; end
+
+    # Raised when the request is forbidden (403)
+    class ForbiddenError < Error; end
+
+    # Raised when a resource is not found (404)
+    class NotFoundError < Error; end
+
+    # Raised when validation fails (422)
+    class ValidationError < Error
+      attr_reader :errors
+
+      # Channex details the rejected fields by name. Only the names join the message, which reaches error
+      # tracking: the details can echo the values sent.
+      def initialize(message = nil, errors: {}, **kwargs)
+        @errors = errors
+        fields = errors.is_a?(Hash) ? errors.keys : []
+        super(fields.any? ? "#{message}: #{fields.join(", ")}" : message, **kwargs)
+      end
+    end
+
+    # Raised when rate limited (429)
+    class RateLimitError < Error
+      attr_reader :retry_after
+
+      def initialize(message = nil, retry_after: nil, **kwargs)
+        @retry_after = retry_after
+        super(message, **kwargs)
+      end
+    end
+
+    # Raised for server errors (5xx)
+    class ServerError < Error; end
+
+    # Raised for connection/network errors
+    class ConnectionError < Error; end
+
+    # Raised when request times out
+    class TimeoutError < Error; end
+
+    # Raised for invalid configuration
+    class ConfigurationError < Error; end
+
+    # Errors that repeating the same request can't fix.
+    PERMANENT = [AuthenticationError, ForbiddenError, NotFoundError, ValidationError].freeze
+  end
+end

data/lib/channex/object.rb

@@ -0,0 +1,201 @@
+module Channex
+  # Base class for typed API response objects
+  #
+  # Provides typed accessor methods while maintaining hash compatibility
+  # for backwards compatibility and easy data exploration.
+  #
+  # @example Basic usage
+  #   revision = Channex::Objects::BookingRevision.new(data)
+  #   revision.id                      # => "uuid" (typed accessor)
+  #   revision["id"]                   # => "uuid" (hash access)
+  #   revision.dig("customer", "name") # => "John"
+  #   revision.to_h                    # => {"id" => "uuid", ...}
+  #
+  # @example Defining attributes in subclasses
+  #   class BookingRevision < Channex::Object
+  #     attribute :id
+  #     attribute :customer, type: Customer
+  #     array_attribute :rooms, type: BookingRoom
+  #   end
+  #
+  class Object
+    include Enumerable
+
+    class << self
+      # Define a typed attribute with optional type coercion
+      #
+      # @param name [Symbol] Attribute name (becomes the method name)
+      # @param type [Class, nil] Optional class for nested object wrapping
+      # @param key [String, nil] Override the hash key (defaults to name.to_s)
+      #
+      # @example Simple attribute
+      #   attribute :id
+      #
+      # @example Nested object
+      #   attribute :customer, type: Customer
+      #
+      # @example Different key name
+      #   attribute :email, key: "mail"
+      #
+      def attribute(name, type: nil, key: nil)
+        key ||= name.to_s
+
+        attributes[name] = {key: key, type: type}
+
+        define_method(name) do
+          value = @data[key]
+          return nil if value.nil?
+
+          if type
+            @wrapped_values[name] ||= wrap_value(value, type)
+          else
+            value
+          end
+        end
+      end
+
+      # Define an array attribute with typed elements
+      #
+      # @param name [Symbol] Attribute name
+      # @param type [Class] Class for array element wrapping
+      # @param key [String, nil] Override the hash key
+      #
+      # @example
+      #   array_attribute :rooms, type: BookingRoom
+      #
+      def array_attribute(name, type:, key: nil)
+        key ||= name.to_s
+
+        attributes[name] = {key: key, type: type, array: true}
+
+        define_method(name) do
+          @wrapped_values[name] ||= begin
+            raw = @data[key] || []
+            raw.map { |item| wrap_value(item, type) }
+          end
+        end
+      end
+
+      # Registry of defined attributes for this class
+      # @return [Hash]
+      def attributes
+        @attributes ||= {}
+      end
+
+      # Construct an object from raw API data
+      #
+      # @param data [Hash, nil] Raw API response data
+      # @return [Object, nil] Wrapped object or nil if data is nil
+      def construct_from(data)
+        return nil if data.nil?
+        new(data)
+      end
+    end
+
+    # @param data [Hash] Raw API response data
+    def initialize(data)
+      @data = data.is_a?(Hash) ? data : {}
+      @wrapped_values = {}
+    end
+
+    # Hash-like access for backwards compatibility
+    #
+    # @param key [String, Symbol] Hash key
+    # @return [Object, nil] Value at key
+    def [](key)
+      @data[key.to_s]
+    end
+
+    # Deep access for nested data
+    #
+    # @param keys [Array<String, Symbol>] Path of keys
+    # @return [Object, nil] Value at path
+    def dig(*keys)
+      @data.dig(*keys.map(&:to_s))
+    end
+
+    # Return the underlying hash data
+    # @return [Hash]
+    def to_h
+      @data.dup
+    end
+    alias_method :to_hash, :to_h
+
+    # JSON serialization
+    # @return [String]
+    def to_json(*args)
+      @data.to_json(*args)
+    end
+
+    # Rails JSON serialization support
+    # @return [Hash]
+    def as_json(*args)
+      @data.as_json(*args)
+    end
+
+    # Enumerable support - iterate over key/value pairs
+    def each(&block)
+      @data.each(&block)
+    end
+
+    # @return [Array<String>] All keys in the data
+    delegate :keys, to: :@data
+
+    # @return [Array] All values in the data
+    delegate :values, to: :@data
+
+    # Check if a key exists
+    # @param key [String, Symbol]
+    # @return [Boolean]
+    def key?(key)
+      @data.key?(key.to_s)
+    end
+    alias_method :has_key?, :key?
+
+    # Fetch with default value support
+    # @param key [String, Symbol]
+    # @return [Object]
+    def fetch(key, *args, &block)
+      @data.fetch(key.to_s, *args, &block)
+    end
+
+    # Debug representation
+    # @return [String]
+    def inspect
+      "#<#{self.class.name} #{@data.inspect}>"
+    end
+
+    # @return [String]
+    def to_s
+      inspect
+    end
+
+    # Equality based on underlying data
+    # @param other [Object, Hash]
+    # @return [Boolean]
+    def ==(other)
+      case other
+      when Channex::Object
+        @data == other.to_h
+      when Hash
+        @data == other
+      else
+        false
+      end
+    end
+
+    private
+
+    def wrap_value(value, type)
+      return nil if value.nil?
+
+      if type.respond_to?(:construct_from)
+        type.construct_from(value)
+      elsif type.is_a?(Class) && type < Channex::Object
+        type.new(value)
+      else
+        value
+      end
+    end
+  end
+end

data/lib/channex/objects/booking_revision.rb

@@ -0,0 +1,124 @@
+module Channex
+  module Objects
+    # Booking revision from Channex API
+    #
+    # Booking revisions are snapshots of bookings at a given time.
+    # Each time an OTA provides an update, a new revision is created.
+    #
+    # @example Basic usage
+    #   revision.id                      # => "uuid"
+    #   revision.status                  # => "new"
+    #   revision.new?                    # => true
+    #   revision.customer.full_name      # => "John Doe"
+    #   revision.rooms.first.nights      # => 3
+    #
+    # @example Hash access still works
+    #   revision["booking_id"]           # => "uuid"
+    #   revision.dig("customer", "mail") # => "john@example.com"
+    #
+    class BookingRevision < Channex::Object
+      # Core identifiers
+      attribute :id
+      attribute :booking_id
+      attribute :property_id
+      attribute :unique_id
+      attribute :system_id
+
+      # OTA information
+      attribute :ota_name
+      attribute :ota_reservation_code
+
+      # Status and timing
+      attribute :status
+      attribute :inserted_at
+
+      # Booking dates
+      attribute :arrival_date
+      attribute :departure_date
+      attribute :arrival_hour
+
+      # Financial
+      attribute :amount
+      attribute :currency
+      attribute :ota_commission
+      attribute :payment_collect
+      attribute :payment_type
+
+      # Other
+      attribute :notes
+
+      # Nested objects
+      attribute :customer, type: Customer
+      attribute :occupancy, type: Occupancy
+      attribute :guarantee, type: Guarantee
+
+      # Arrays
+      array_attribute :rooms, type: BookingRoom
+      array_attribute :services, type: Service
+
+      # Status check helpers
+      # @return [Boolean]
+      def new?
+        status == "new"
+      end
+
+      # @return [Boolean]
+      def modified?
+        status == "modified"
+      end
+
+      # @return [Boolean]
+      def cancelled?
+        status == "cancelled"
+      end
+
+      # Arrival date as Date object
+      # @return [Date, nil]
+      def check_in_date
+        Date.parse(arrival_date) if arrival_date
+      end
+
+      # Departure date as Date object
+      # @return [Date, nil]
+      def check_out_date
+        Date.parse(departure_date) if departure_date
+      end
+
+      # Timestamp when revision was received
+      # @return [Time, nil]
+      def received_at
+        Time.parse(inserted_at) if inserted_at
+      end
+
+      # Total booking amount as Money object (if money gem is available)
+      # @return [Money, nil]
+      def total_amount
+        return nil unless amount && currency
+        return nil unless defined?(Money)
+
+        Money.from_amount(BigDecimal(amount.to_s), currency)
+      end
+
+      # OTA commission as Money object (if money gem is available)
+      # @return [Money, nil]
+      def commission_amount
+        return nil unless ota_commission && currency
+        return nil unless defined?(Money)
+
+        Money.from_amount(BigDecimal(ota_commission.to_s), currency)
+      end
+
+      # Whether payment should be collected by the property
+      # @return [Boolean]
+      def collect_payment?
+        payment_collect == "property" || payment_collect.nil?
+      end
+
+      # Whether payment was already collected by the OTA
+      # @return [Boolean]
+      def prepaid?
+        payment_collect == "ota"
+      end
+    end
+  end
+end

data/lib/channex/objects/booking_room.rb

@@ -0,0 +1,68 @@
+module Channex
+  module Objects
+    # Individual room within a booking revision
+    #
+    # @example
+    #   room.room_type_id      # => "uuid"
+    #   room.check_in_date     # => Date
+    #   room.check_out_date    # => Date
+    #   room.nights            # => 3
+    #   room.occupancy.adults  # => 2
+    #   room.guests.first.name # => "John"
+    #
+    class BookingRoom < Channex::Object
+      attribute :booking_room_id
+      attribute :ota_unique_id
+      attribute :room_type_id
+      attribute :rate_plan_id
+      attribute :checkin_date
+      attribute :checkout_date
+      attribute :amount
+      attribute :occupancy, type: Occupancy
+      array_attribute :guests, type: Guest
+      array_attribute :taxes, type: Tax
+      array_attribute :services, type: Service
+
+      # Check-in date as Date object
+      # @return [Date, nil]
+      def check_in_date
+        Date.parse(checkin_date) if checkin_date
+      end
+
+      # Check-out date as Date object
+      # @return [Date, nil]
+      def check_out_date
+        Date.parse(checkout_date) if checkout_date
+      end
+
+      # Number of nights for this room
+      # @return [Integer, nil]
+      def nights
+        return nil unless check_in_date && check_out_date
+        (check_out_date - check_in_date).to_i
+      end
+
+      def room_reservation_id
+        meta["room_reservation_id"] || meta["roomreservation_id"]
+      end
+
+      # Daily price breakdown
+      # @return [Hash] Date string keys mapped to price strings
+      def days
+        @data["days"] || {}
+      end
+
+      # Free-form metadata
+      # @return [Hash]
+      def meta
+        @data["meta"] || {}
+      end
+
+      # Parent rate plan ID (when using derived rate plans)
+      # @return [String, nil]
+      def parent_rate_plan_id
+        meta["parent_rate_plan_id"]
+      end
+    end
+  end
+end

data/lib/channex/objects/company.rb

@@ -0,0 +1,16 @@
+module Channex
+  module Objects
+    # Company information nested within Customer
+    #
+    # @example
+    #   company.title        # => "Acme Corp"
+    #   company.number       # => "12345678"
+    #   company.number_type  # => "vat"
+    #
+    class Company < Channex::Object
+      attribute :title
+      attribute :number
+      attribute :number_type
+    end
+  end
+end

data/lib/channex/objects/customer.rb

@@ -0,0 +1,43 @@
+module Channex
+  module Objects
+    # Customer information from a booking
+    #
+    # @example
+    #   customer.name       # => "John"
+    #   customer.surname    # => "Doe"
+    #   customer.full_name  # => "John Doe"
+    #   customer.email      # => "john@example.com"
+    #   customer.company    # => Channex::Objects::Company
+    #
+    class Customer < Channex::Object
+      attribute :name
+      attribute :surname
+      attribute :mail
+      attribute :phone
+      attribute :country
+      attribute :city
+      attribute :address
+      attribute :zip
+      attribute :language
+      attribute :company, type: Company
+
+      # Alias for mail (more intuitive name)
+      # @return [String, nil]
+      def email
+        mail
+      end
+
+      # Combined first and last name
+      # @return [String, nil]
+      def full_name
+        [name, surname].compact.join(" ").presence
+      end
+
+      # Free-form metadata
+      # @return [Hash]
+      def meta
+        @data["meta"] || {}
+      end
+    end
+  end
+end

data/lib/channex/objects/guarantee.rb

@@ -0,0 +1,21 @@
+module Channex
+  module Objects
+    # Payment guarantee/card information
+    #
+    # Note: Contains sensitive payment data. Handle with care.
+    #
+    # @example
+    #   guarantee.card_type       # => "visa"
+    #   guarantee.card_number     # => "4111111111111111"
+    #   guarantee.cardholder_name # => "John Doe"
+    #   guarantee.expiration_date # => "12/25"
+    #
+    class Guarantee < Channex::Object
+      attribute :card_number
+      attribute :card_type
+      attribute :cardholder_name
+      attribute :cvv
+      attribute :expiration_date
+    end
+  end
+end

data/lib/channex/objects/guest.rb

@@ -0,0 +1,21 @@
+module Channex
+  module Objects
+    # Individual guest information within a room
+    #
+    # @example
+    #   guest.name       # => "John"
+    #   guest.surname    # => "Doe"
+    #   guest.full_name  # => "John Doe"
+    #
+    class Guest < Channex::Object
+      attribute :name
+      attribute :surname
+
+      # Combined first and last name
+      # @return [String, nil]
+      def full_name
+        [name, surname].compact.join(" ").presence
+      end
+    end
+  end
+end

data/lib/channex/objects/message.rb

@@ -0,0 +1,95 @@
+module Channex
+  module Objects
+    # A single message inside a Message Thread.
+    #
+    # The API returns messages as JSON:API resource nodes — the text lives under
+    # `attributes`, the identifier under `id` and the owning thread under
+    # `relationships`. {.from_resource} flattens that node so a message is one
+    # hash you can read, store and re-wrap.
+    #
+    # @example
+    #   message.sender       # => "guest"
+    #   message.from_guest?  # => true
+    #   message.message      # => "What time is check-in?"
+    #   message.thread_id    # => "4e160f0b-016a-424a-a30d-a9f0a8b1cbaa"
+    #
+    class Message < Channex::Object
+      # Who put the message on the thread. `system` marks messages Channex
+      # generates itself, such as an Airbnb inquiry.
+      SENDERS = %w[guest property system].freeze
+
+      attribute :id
+      attribute :message
+      attribute :sender
+      attribute :inserted_at
+      attribute :updated_at
+
+      # Lifted out of `relationships`
+      attribute :thread_id
+      attribute :user_id
+
+      # Flatten a JSON:API resource node into a message
+      #
+      # @param node [Hash, nil] A `{"id", "attributes", "relationships"}` node
+      # @return [Message, nil]
+      def self.from_resource(node)
+        return nil if node.nil?
+
+        attributes = node["attributes"] || {}
+        relationships = node["relationships"] || {}
+
+        new(
+          attributes.merge(
+            "id" => node["id"],
+            "thread_id" => relationships.dig("message_thread", "data", "id"),
+            "user_id" => relationships.dig("user", "data", "id")
+          ).compact
+        )
+      end
+
+      # Attachments as returned by the API. Channex sends relative URLs, which
+      # have to be prefixed with the API base URL to be fetched.
+      #
+      # @return [Array]
+      def attachments
+        @data["attachments"] || []
+      end
+
+      # Attachment URLs, whether the API sent bare strings or objects.
+      #
+      # @return [Array<String>]
+      def attachment_urls
+        attachments.filter_map do |attachment|
+          attachment.is_a?(Hash) ? attachment["url"] : attachment
+        end
+      end
+
+      # @return [Boolean]
+      def attachments?
+        !attachments.empty?
+      end
+
+      # Provider-specific extras, e.g. the booking details of an Airbnb inquiry.
+      #
+      # @return [Hash]
+      def meta
+        @data["meta"] || {}
+      end
+
+      # @return [Boolean]
+      def from_guest?
+        sender == "guest"
+      end
+
+      # @return [Boolean]
+      def from_property?
+        sender == "property"
+      end
+
+      # @return [Boolean]
+      def from_system?
+        sender == "system"
+      end
+    end
+  end
+end