smily_cli 0.1.0

data/lib/smily_cli/query_options.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module SmilyCli
+  # Turns user-facing flags (`--filter status=booked`, `--query per_page=100`,
+  # `--fields id,name`, `--include availability`) into the flat query hash the
+  # API v3 expects. v3 filtering is plain query parameters, so `--filter` and
+  # `--query` share one mechanism; `--filter` simply reads as intent.
+  module QueryOptions
+    # Comparison operators the API v3 filter DSL accepts (mirrors the operators
+    # reported per attribute by the `resource_schema` / `api_v3_resource_schema`
+    # tool). Used to recognize the `attribute[op]=value` filter syntax.
+    OPERATORS = %w[eq not_eq gt gteq lt lteq in matches does_not_match].freeze
+
+    module_function
+
+    # Parse `key=value` strings into a hash. A repeated key accumulates into an
+    # array (so `--filter status=booked --filter status=tentative` sends both).
+    #
+    # @param pairs [Array<String>]
+    # @return [Hash{String=>Object}]
+    # @raise [UsageError] when an entry has no `=`
+    def parse_pairs(pairs)
+      Array(pairs).each_with_object({}) do |pair, acc|
+        key, value = split_pair(pair)
+        acc[key] = if acc.key?(key)
+                     Array(acc[key]) << value
+                   else
+                     value
+                   end
+      end
+    end
+
+    # Parse `key=value` / `key[op]=value` filter pairs into the *structured*
+    # filter object the API v3 list tool accepts (via MCP `api_v3_list`):
+    #
+    #   * a bare (coerced) value for plain equality,
+    #   * an `{ "op", "value" }` object for a single operator, and
+    #   * an array of such objects when one attribute carries more than one
+    #     condition (AND) — e.g. a numeric or date range.
+    #
+    # Examples:
+    #   ["currency=EUR"]                      => { "currency" => "EUR" }
+    #   ["adults[gteq]=2"]                    => { "adults" => { "op" => "gteq", "value" => 2 } }
+    #   ["final_price[gteq]=600",
+    #    "final_price[lt]=800"]               => { "final_price" =>
+    #                                              [ { "op" => "gteq", "value" => 600 },
+    #                                                { "op" => "lt",   "value" => 800 } ] }
+    #   ["reference[in]=A,B"]                 => { "reference" => { "op" => "in", "value" => %w[A B] } }
+    #
+    # Values are coerced (integer/float/boolean) so numeric attributes compare
+    # as numbers rather than strings; ISO 8601 timestamps stay strings.
+    #
+    # @param pairs [Array<String>]
+    # @return [Hash{String=>Object}]
+    # @raise [UsageError] on a missing `=` or an unknown operator
+    def parse_filter(pairs)
+      Array(pairs).each_with_object({}) do |pair, acc|
+        key, value = split_pair(pair)
+        attribute, operator = parse_operator(key)
+        merge_condition(acc, attribute, condition_for(operator, value))
+      end
+    end
+
+    # Assemble the final query hash for a request from the standard flags.
+    #
+    # @param fields [Array<String>, nil] sparse fieldset
+    # @param include [Array<String>, String, nil] associations to sideload
+    # @param filter [Array<String>] `key=value` filter pairs
+    # @param query [Array<String>] `key=value` passthrough params
+    # @return [Hash{String=>Object}]
+    def build(fields: nil, include: nil, filter: [], query: [])
+      result = {}
+      result.merge!(parse_pairs(query))
+      result.merge!(parse_pairs(filter))
+      if (inc = normalize_list(include))
+        result["include"] = inc.join(",")
+      end
+      result["fields"] = fields.join(",") if fields && !fields.empty?
+      result
+    end
+
+    # @api private
+    def split_pair(pair)
+      str = pair.to_s
+      key, sep, value = str.partition("=")
+      raise UsageError, "Invalid key=value pair #{pair.inspect} (expected e.g. status=booked)" if sep.empty?
+
+      [key.strip, value]
+    end
+
+    # A single filter condition: an `{ op, value }` object when an operator was
+    # given, else the bare coerced equality value.
+    # @api private
+    def condition_for(operator, value)
+      return coerce_scalar(value) unless operator
+
+      { "op" => operator, "value" => coerce_filter_value(operator, value) }
+    end
+
+    # Split an `attribute[op]` key into `[attribute, op]`, validating the
+    # operator; a plain `attribute` returns `[attribute, nil]` (equality).
+    # @api private
+    def parse_operator(key)
+      match = key.match(/\A(?<attribute>.+?)\[(?<op>[a-z_]+)\]\z/)
+      return [key, nil] unless match
+
+      operator = match[:op]
+      unless OPERATORS.include?(operator)
+        raise UsageError,
+              "Unknown filter operator #{operator.inspect} in #{key.inspect}. Valid: #{OPERATORS.join(', ')}."
+      end
+      [match[:attribute], operator]
+    end
+
+    # Add one condition to the filter, arraying (AND) when the attribute already
+    # has one. A bare equality value is promoted to an `{ op: "eq" }` object when
+    # it must share an array with operator conditions, keeping the array uniform.
+    # @api private
+    def merge_condition(filter, attribute, condition)
+      if filter.key?(attribute)
+        existing = filter[attribute]
+        list = existing.is_a?(Array) ? existing : [as_operator(existing)]
+        filter[attribute] = list << as_operator(condition)
+      else
+        filter[attribute] = condition
+      end
+    end
+
+    # @api private
+    def as_operator(condition)
+      condition.is_a?(Hash) ? condition : { "op" => "eq", "value" => condition }
+    end
+
+    # `in` takes a comma-separated set; every other operator a single value.
+    # @api private
+    def coerce_filter_value(operator, value)
+      return value.split(",").map { |v| coerce_scalar(v.strip) } if operator == "in"
+
+      coerce_scalar(value)
+    end
+
+    # Coerce a raw string into the natural JSON scalar so numeric/boolean
+    # attributes compare as themselves; anything else (incl. ISO 8601) stays a
+    # string.
+    # @api private
+    def coerce_scalar(value)
+      case value
+      when /\A-?\d+\z/ then value.to_i
+      when /\A-?\d+\.\d+\z/ then Float(value)
+      when "true" then true
+      when "false" then false
+      else value
+      end
+    end
+
+    # @api private
+    def normalize_list(value)
+      return nil if value.nil?
+
+      list = Array(value).flat_map { |v| v.to_s.split(",") }.map(&:strip).reject(&:empty?)
+      list.empty? ? nil : list
+    end
+  end
+end

data/lib/smily_cli/redaction.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module SmilyCli
+  # Scrubs secrets out of any text before it is written to a log or debug
+  # stream. `--verbose` wires the HTTP stacks' debug output through here so that
+  # access tokens, client secrets and refresh tokens never reach stderr in the
+  # clear (verbose output routinely ends up pasted into tickets/chat).
+  module Redaction
+    PLACEHOLDER = "[REDACTED]"
+
+    # Each pattern captures a leading label ($1) that is kept, and a secret
+    # value ($2) that is replaced.
+    PATTERNS = [
+      /(authorization:\s*bearer\s+)(\S+)/i,
+      /(bearer\s+)([A-Za-z0-9._-]{6,})/i,
+      /(access[_-]?token["'=:\s]+)([^&"'\s]+)/i,
+      /(refresh[_-]?token["'=:\s]+)([^&"'\s]+)/i,
+      /(client[_-]?secret["'=:\s]+)([^&"'\s]+)/i,
+      /(mcp[_-]?token["'=:\s]+)([^&"'\s]+)/i
+    ].freeze
+
+    module_function
+
+    # Return `text` with any recognized secret replaced by {PLACEHOLDER}.
+    #
+    # @param text [Object] coerced to String
+    # @return [String]
+    def scrub(text)
+      PATTERNS.reduce(text.to_s) do |acc, pattern|
+        acc.gsub(pattern) { "#{Regexp.last_match(1)}#{PLACEHOLDER}" }
+      end
+    end
+
+    # Wrap an IO so everything written to it is scrubbed first. Suitable for
+    # `Net::HTTP#set_debug_output`, which appends wire data via `<<`/`write`.
+    #
+    # @param io [IO]
+    # @return [ScrubbedIO]
+    def stream(io)
+      ScrubbedIO.new(io)
+    end
+
+    # An IO-ish wrapper that scrubs every chunk before forwarding it.
+    class ScrubbedIO
+      # @param io [IO]
+      def initialize(io)
+        @io = io
+      end
+
+      def write(string)
+        @io.write(Redaction.scrub(string))
+      end
+
+      def <<(string)
+        write(string)
+        self
+      end
+
+      def print(*strings)
+        strings.each { |string| write(string) }
+        nil
+      end
+
+      def puts(*strings)
+        strings.each { |string| @io.puts(Redaction.scrub(string.to_s)) }
+        nil
+      end
+
+      def flush
+        @io.flush if @io.respond_to?(:flush)
+      end
+    end
+  end
+end

data/lib/smily_cli/registry.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module SmilyCli
+  # The catalog of BookingSync API v3 resources the CLI exposes as first-class
+  # commands. Sourced from the public API reference
+  # (https://developers.bookingsync.com/reference). Resources absent here can
+  # still be reached with `smily api <method> <path>`.
+  module Registry
+    # @api private
+    # Compact DSL row: [command, group, description, opts]
+    # `path` defaults to the command; `readonly` and `singular` are optional.
+    ROWS = [
+      # --- Bookings ---------------------------------------------------------
+      ["bookings",            "Bookings", "Reservations and unavailable periods."],
+      ["bookings_fees",       "Bookings", "Per-booking fees (cleaning, tax, ...)."],
+      ["bookings_payments",   "Bookings", "Per-booking payment line items."],
+      ["bookings_taxes",      "Bookings", "Per-booking tax line items."],
+      ["bookings_tags",       "Bookings", "Booking tags (account taxonomy)."],
+      ["booking_comments",    "Bookings", "Internal comments on bookings."],
+      ["booking_discount_codes", "Bookings", "Booking discount codes configured by the account."],
+      ["booking_discount_code_usages", "Bookings", "Records of discount code applications on bookings."],
+
+      # --- Rentals ----------------------------------------------------------
+      ["rentals",             "Rentals", "Listings / properties."],
+      ["rentals_amenities",   "Rentals", "Per-rental amenity availability."],
+      ["rentals_fees",        "Rentals", "Per-rental fee configuration."],
+      ["rentals_taxes",       "Rentals", "Per-rental tax configuration."],
+      ["rentals_tags",        "Rentals", "Account tags applied to rentals."],
+      ["rentals_contents_overrides", "Rentals", "Per-application content overrides."],
+      ["rental_agreements", "Rentals", "Localized rental agreement contracts."],
+      ["rental_cancelation_policies", "Rentals", "Cancelation policies on rentals."],
+      ["rental_cancelation_policy_items", "Rentals", "Refund tiers of cancelation policies."],
+      ["rental_contacts",     "Rentals", "Contacts linked to rentals."],
+      ["rental_urls",         "Rentals", "External URLs for rentals."],
+      ["rental_link_groups",  "Rentals", "Groups of linked rentals."],
+      ["rental_links",        "Rentals", "Rental-to-link-group memberships."],
+      ["bathrooms",           "Rentals", "Bathroom layout per rental."],
+      ["bedrooms",            "Rentals", "Bedroom layout per rental."],
+      ["living_rooms",        "Rentals", "Living room layout per rental."],
+      ["photos",              "Rentals", "Photos attached to rentals."],
+      ["change_overs",        "Rentals", "Change-over (turnover) days."],
+      ["availabilities",      "Rentals", "Availability windows per rental."],
+      ["special_offers",      "Rentals", "Promotional offers on rentals."],
+
+      # --- Rates & pricing --------------------------------------------------
+      ["rates",               "Rates", "Nightly rates per rental/season."],
+      ["rates_rules",         "Rates", "Pricing rules (min-stay, discounts...)."],
+      ["rates_tables",        "Rates", "Named pricing strategies."],
+      ["seasons",             "Rates", "Pricing seasons."],
+      ["periods",             "Rates", "Date ranges belonging to seasons."],
+      ["los_records",         "Rates", "Length-of-stay precomputed rates.", { readonly: true }],
+      ["nightly_rate_maps",   "Rates", "Nightly rate maps per rental."],
+      ["mid_term_rate_maps",  "Rates", "Mid-term (monthly) rate maps."],
+
+      # --- Clients & people -------------------------------------------------
+      ["clients",             "People", "Guests / customers at account level."],
+      ["hosts",               "People", "Hosts (greeters, on-site staff)."],
+      ["contacts",            "People", "Address book (cleaners, owners...)."],
+      ["inquiries",           "People", "Pre-booking inquiries."],
+      ["reviews",             "People", "Guest reviews of rentals."],
+
+      # --- Inbox ------------------------------------------------------------
+      ["inbox_conversations", "Inbox", "Conversation threads."],
+      ["inbox_messages",      "Inbox", "Messages within conversations."],
+      ["inbox_attachments",   "Inbox", "Attachments on inbox messages."],
+      ["inbox_participants",  "Inbox", "Participants in conversations."],
+
+      # --- Billing & payments ----------------------------------------------
+      ["payments",            "Billing", "Top-level payment transactions."],
+      ["payment_gateways",    "Billing", "Configured payment gateways."],
+      ["fees",                "Billing", "Account-level fee catalog."],
+      ["fees_taxes",          "Billing", "Joins between fees and taxes."],
+      ["taxes",               "Billing", "Account-level tax catalog."],
+      ["tax_rules",           "Billing", "Rules controlling when taxes apply."],
+
+      # --- Catalog & account ------------------------------------------------
+      ["accounts",            "Account", "Accounts installed for the app.", { readonly: true }],
+      ["applications",        "Account", "Applications registered on the account.", { readonly: true }],
+      ["amenities",           "Account", "Global amenity catalog.", { readonly: true }],
+      ["destinations",        "Account", "Destinations for the account's rentals."],
+      ["sources",             "Account", "Booking sources / channels."],
+      ["hosts_reviews",       "Account", "Reviews written by hosts about guests.", { path: "host_reviews" }],
+      ["webhooks",            "Account", "Configured outbound webhooks."]
+    ].freeze
+    private_constant :ROWS
+
+    # @return [Array<Resource>] every registered resource, ordered as declared
+    def self.all
+      @all ||= ROWS.map do |command, group, description, opts|
+        opts ||= {}
+        Resource.new(
+          command: command,
+          path: opts[:path] || command,
+          singular: opts[:singular] || singularize(command),
+          group: group,
+          description: description,
+          readonly: opts.fetch(:readonly, false)
+        )
+      end.freeze
+    end
+
+    # @return [Array<String>] every command word, sorted
+    def self.commands
+      @commands ||= all.map(&:command).sort.freeze
+    end
+
+    # Look up a resource by its command word.
+    #
+    # @param command [String]
+    # @return [Resource, nil]
+    def self.find(command)
+      index[command.to_s]
+    end
+
+    # Like {find} but raises a helpful {UsageError} when unknown.
+    #
+    # @param command [String]
+    # @return [Resource]
+    def self.fetch(command)
+      find(command) || raise(UsageError, unknown_message(command))
+    end
+
+    # Registered resources grouped by their {Resource#group}, preserving the
+    # declaration order of both groups and members.
+    #
+    # @return [Hash{String => Array<Resource>}]
+    def self.grouped
+      all.each_with_object({}) do |resource, groups|
+        (groups[resource.group] ||= []) << resource
+      end
+    end
+
+    # @api private
+    def self.index
+      @index ||= all.to_h { |r| [r.command, r] }.freeze
+    end
+
+    # @api private
+    def self.singularize(command)
+      # Good-enough English singularization for the labels we actually use.
+      case command
+      when /ies\z/ then command.sub(/ies\z/, "y")
+      when /ses\z/ then command.sub(/es\z/, "")
+      when /s\z/   then command.sub(/s\z/, "")
+      else command
+      end
+    end
+
+    # @api private
+    def self.unknown_message(command)
+      suggestion = commands.min_by { |c| levenshtein(command.to_s, c) }
+      base = "Unknown resource #{command.inspect}."
+      hint = suggestion ? " Did you mean #{suggestion.inspect}?" : ""
+      "#{base}#{hint} Run `smily resources` to list them, or use `smily api`."
+    end
+    private_class_method :unknown_message
+
+    # @api private
+    def self.levenshtein(from, to)
+      row = (0..to.length).to_a
+      (1..from.length).each do |i|
+        prev = row[0]
+        row[0] = i
+        (1..to.length).each do |j|
+          current = row[j]
+          cost = from[i - 1] == to[j - 1] ? 0 : 1
+          row[j] = [row[j] + 1, row[j - 1] + 1, prev + cost].min
+          prev = current
+        end
+      end
+      row[to.length]
+    end
+    private_class_method :levenshtein
+  end
+end

data/lib/smily_cli/resource.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module SmilyCli
+  # A single API v3 resource the CLI knows about by name: the command word the
+  # user types (`rentals`), the HTTP path it maps to (`rentals`, or
+  # `booking/discount_codes`), the singular label for help text, and grouping
+  # metadata used by `smily resources`.
+  #
+  # Anything *not* in the {Registry} is still reachable through `smily api`,
+  # so the registry is about ergonomics and discoverability, not a hard gate.
+  Resource = Struct.new(
+    :command, :path, :singular, :group, :description, :readonly,
+    keyword_init: true
+  ) do
+    # The JSON:API top-level key used in request/response bodies for this
+    # resource. For v3 this is the pluralized resource name, i.e. the last
+    # path segment (`booking/discount_codes` -> `discount_codes`).
+    #
+    # @return [String]
+    def resource_key
+      path.split("/").last
+    end
+
+    # @return [Boolean] whether write commands (create/update/delete) apply
+    def writable?
+      !readonly
+    end
+
+    # Path to the collection endpoint (e.g. "rentals").
+    # @return [String]
+    def collection_path
+      path
+    end
+
+    # Path to a member endpoint (e.g. "rentals/42").
+    # @param id [String, Integer]
+    # @return [String]
+    def member_path(id)
+      "#{path}/#{id}"
+    end
+  end
+end

data/lib/smily_cli/resource_command.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module SmilyCli
+  # The set of subcommands every registered resource gets: `list`, `get`, and
+  # (unless the resource is read-only) `create`, `update`, `delete`. One bound
+  # subclass is generated per {Resource} via {.bind}; the bound class carries
+  # the resource so the shared command bodies know which path/key to use.
+  class ResourceCommand < BaseCommand
+    CLIOptions.connection(self)
+    CLIOptions.output(self)
+
+    # Generated subclasses live here so they have real constant names (Thor
+    # derives a command namespace from the class name).
+    module Bound; end
+
+    class << self
+      # @return [Resource, nil] the resource this class is bound to
+      attr_reader :resource
+
+      # Build a Thor subcommand class bound to `resource`.
+      #
+      # @param resource [Resource]
+      # @return [Class<ResourceCommand>]
+      def bind(resource)
+        klass = Class.new(self)
+        klass.instance_variable_set(:@resource, resource)
+        # Make Thor render help/usage as `smily <command> ...` rather than
+        # deriving a namespace from the generated constant name.
+        klass.namespace(resource.command)
+        klass.remove_command("create", "update", "delete") if resource.readonly
+        klass.remove_command("tree")
+        Bound.const_set("#{camelize(resource.command)}Command", klass)
+        klass
+      end
+
+      # @api private
+      def camelize(command)
+        command.split(%r{[_/]}).map(&:capitalize).join
+      end
+    end
+
+    desc "list", "List records (supports --filter, --fields, pagination)"
+    long_desc <<~DESC
+      List records for this resource.
+
+      Filtering uses plain query parameters, e.g.:
+        smily bookings list --filter status=booked from=2026-01-01
+        smily rentals list --fields id name --limit 10
+        smily bookings list --all -o ndjson
+
+      Use --all to fetch every page, or --limit N to stop after N records.
+    DESC
+    method_option :filter, type: :array, banner: "k=v", desc: "Filter by query params (key=value)"
+    method_option :query, type: :array, banner: "k=v", desc: "Extra raw query params (key=value)"
+    method_option :include, type: :array, banner: "assoc", desc: "Sideload associations"
+    method_option :limit, type: :numeric, aliases: "-n", desc: "Stop after N records (follows pages)"
+    method_option :page, type: :numeric, desc: "Fetch a specific page"
+    method_option :per_page, type: :numeric, desc: "Page size"
+    method_option :all, type: :boolean, desc: "Fetch every page"
+    def list
+      query = QueryOptions.build(
+        fields: context.fields,
+        include: options["include"],
+        filter: options["filter"] || [],
+        query: options["query"] || []
+      )
+      result = client.list(
+        resource.collection_path,
+        query: query,
+        limit: options["limit"],
+        page: options["page"],
+        per_page: options["per_page"],
+        all: options["all"]
+      )
+      render_result(result)
+    end
+
+    desc "get ID", "Get a single record by ID"
+    method_option :include, type: :array, banner: "assoc", desc: "Sideload associations"
+    def get(id)
+      query = QueryOptions.build(fields: context.fields, include: options["include"])
+      render_result(client.get(resource.collection_path, id, query: query))
+    end
+
+    desc "create", "Create a record from --data JSON"
+    long_desc <<~DESC
+      Create a record. Provide the attributes as a JSON object with --data;
+      the resource envelope is added for you:
+
+        smily rentals create --data '{"name":"Villa"}'
+        smily clients create --data @client.json
+
+      For nested creates, point --path at the parent collection (the resource
+      envelope key is unchanged):
+
+        smily bookings create --path rentals/42/bookings --data '{"start_at":"..."}'
+    DESC
+    method_option :data, type: :string, aliases: "-d", banner: "JSON|@file|-",
+                         desc: "Attributes as JSON, @file, or - for stdin"
+    method_option :path, type: :string, banner: "PATH",
+                         desc: "Override the endpoint path (for nested creates)"
+    def create
+      path = options["path"] || resource.collection_path
+      render_result(client.create(path, resource.resource_key, require_data))
+    end
+
+    desc "update ID", "Update a record from --data JSON"
+    method_option :data, type: :string, aliases: "-d", banner: "JSON|@file|-",
+                         desc: "Attributes as JSON, @file, or - for stdin"
+    def update(id)
+      render_result(client.update(resource.collection_path, resource.resource_key, id, require_data))
+    end
+
+    desc "delete ID", "Delete (or cancel) a record by ID"
+    method_option :yes, type: :boolean, aliases: "-y", desc: "Skip the confirmation prompt"
+    method_option :data, type: :string, aliases: "-d", banner: "JSON|@file|-",
+                         desc: "Optional JSON body (e.g. cancelation_reason)"
+    def delete(id)
+      confirm!("Delete #{resource.singular} #{id}?")
+      body = options["data"] ? wrap_delete_body(parse_data(options["data"])) : nil
+      client.delete(resource.collection_path, id, body: body)
+      success("Deleted #{resource.singular} #{id}.")
+    end
+
+    no_commands do
+      # @return [Resource] the resource bound to this command class
+      def resource
+        self.class.resource
+      end
+
+      # Wrap a delete/cancel body in the resource envelope when needed.
+      # @api private
+      def wrap_delete_body(attrs)
+        return attrs if attrs.is_a?(Hash) && attrs.key?(resource.resource_key)
+
+        { resource.resource_key => [attrs] }
+      end
+    end
+  end
+end