smily_cli 0.1.0

data/lib/smily_cli/result.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "json"
+
+module SmilyCli
+  # A normalized view over one or more API v3 responses. It pulls the record
+  # array out of the JSON:API envelope (the single top-level key that isn't
+  # `links`/`linked`/`meta`), while keeping the raw envelope, `meta`, sideloaded
+  # `linked` records, pagination relations and rate-limit headers available for
+  # formatters and verbose output.
+  class Result
+    SPECIAL_KEYS = %w[links linked meta].freeze
+
+    # @return [Array<Hash>] the resource records (always an array)
+    attr_reader :records
+    # @return [Hash, nil] the raw parsed envelope of the last response
+    attr_reader :envelope
+    # @return [Hash, nil] JSON:API `meta`
+    attr_reader :meta
+    # @return [Hash, nil] sideloaded associations (`linked`)
+    attr_reader :linked
+    # @return [Integer, nil] HTTP status of the last response
+    attr_reader :status
+    # @return [Hash] response headers of the last response
+    attr_reader :headers
+    # @return [String, nil] resolved JSON:API key the records live under
+    attr_reader :key
+
+    # @param records [Array<Hash>]
+    # @param single [Boolean] whether this represents one member (get/create)
+    # @param envelope [Hash, nil]
+    # @param key [String, nil]
+    # @param status [Integer, nil]
+    # @param headers [Hash]
+    def initialize(records:, single: false, envelope: nil, key: nil, status: nil, headers: {})
+      @records = records
+      @single = single
+      @envelope = envelope
+      @key = key
+      @meta = envelope.is_a?(Hash) ? envelope["meta"] : nil
+      @linked = envelope.is_a?(Hash) ? envelope["linked"] : nil
+      @status = status
+      @headers = headers || {}
+    end
+
+    # Build a Result from a single {BookingSync::API::Response}.
+    #
+    # @param response [BookingSync::API::Response, nil] nil for 204 No Content
+    # @param single [Boolean]
+    # @return [Result]
+    def self.from_response(response, single: false)
+      return empty(single: single) if response.nil?
+
+      body = parse(response.body)
+      key = resource_key(body)
+      records = extract_records(body, key)
+      new(
+        records: records,
+        single: single,
+        envelope: body,
+        key: key,
+        status: response.status,
+        headers: response.headers
+      )
+    end
+
+    # An empty result (e.g. a 204 delete). `records` is empty.
+    #
+    # @return [Result]
+    def self.empty(single: false, status: nil, headers: {})
+      new(records: [], single: single, envelope: nil, key: nil, status: status, headers: headers)
+    end
+
+    # Build a Result from an already-parsed JSON:API envelope (e.g. the payload
+    # an MCP tool returns), rather than an HTTP response.
+    #
+    # @param body [Hash]
+    # @param single [Boolean]
+    # @return [Result]
+    def self.from_body(body, single: false)
+      key = resource_key(body)
+      new(records: extract_records(body, key), single: single, envelope: body, key: key)
+    end
+
+    # @return [Boolean] whether this result represents a single member
+    def single?
+      @single
+    end
+
+    # @return [Hash, nil] the sole record, when {#single?}
+    def record
+      records.first
+    end
+
+    # @return [Boolean]
+    def empty?
+      records.empty?
+    end
+
+    # @return [Integer]
+    def count
+      records.length
+    end
+
+    # Remaining requests in the current rate-limit window, if reported.
+    #
+    # @return [Integer, nil]
+    def rate_limit_remaining
+      value = headers["X-RateLimit-Remaining"] || headers["x-ratelimit-remaining"]
+      value&.to_i
+    end
+
+    # Total number of pages reported by the API, if any.
+    #
+    # @return [Integer, nil]
+    def total_pages
+      value = headers["X-Total-Pages"] || headers["x-total-pages"]
+      value&.to_i
+    end
+
+    # @api private
+    def self.parse(raw)
+      return {} if raw.nil? || raw.to_s.empty?
+
+      JSON.parse(raw)
+    rescue JSON::ParserError
+      {}
+    end
+
+    # @api private
+    def self.resource_key(body)
+      return nil unless body.is_a?(Hash)
+
+      (body.keys.map(&:to_s) - SPECIAL_KEYS).first
+    end
+
+    # @api private
+    def self.extract_records(body, key)
+      return [] unless body.is_a?(Hash) && key
+
+      # v3 always wraps records in an array, but tolerate a bare object too.
+      case (value = body[key])
+      when Array then value
+      when nil then []
+      else [value]
+      end
+    end
+  end
+end

data/lib/smily_cli/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SmilyCli
+  VERSION = "0.1.0"
+end

data/lib/smily_cli.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+
+require_relative "smily_cli/version"
+require_relative "smily_cli/errors"
+
+# SmilyCli is a command-line client for the BookingSync (Smily) API v3.
+#
+# The library layer (everything under {SmilyCli}) is deliberately usable on its
+# own, without Thor: build a {SmilyCli::Context}, hand it to a
+# {SmilyCli::Client}, and render results with {SmilyCli::Formatters}. The Thor
+# command layer ({SmilyCli::CLI} and friends) autoloads lazily, so requiring the
+# library does not pull in Thor until the command classes are actually touched.
+module SmilyCli
+  # The Thor-powered command-line interface. Referencing the constant autoloads
+  # (and thereby `require`s Thor); kept behind a method so the entry point reads
+  # as `SmilyCli.cli.start`.
+  #
+  # @return [Class] the {SmilyCli::CLI} Thor class
+  def self.cli
+    CLI
+  end
+end
+
+# Autoload everything under lib/smily_cli/**. version.rb and errors.rb hold a
+# bare constant and a multi-class hierarchy respectively (neither maps 1:1 to a
+# file name), so they are required eagerly above and ignored by the loader.
+loader = Zeitwerk::Loader.for_gem
+loader.inflector.inflect(
+  "cli" => "CLI",
+  "cli_options" => "CLIOptions",
+  "oauth" => "OAuth"
+)
+loader.ignore("#{__dir__}/smily_cli/version.rb")
+loader.ignore("#{__dir__}/smily_cli/errors.rb")
+loader.setup

data/sig/smily_cli.rbs

@@ -0,0 +1,21 @@
+module SmilyCli
+  VERSION: String
+
+  def self.cli: () -> untyped
+
+  class Error < StandardError
+    def exit_status: () -> Integer
+  end
+
+  class ConfigurationError < Error
+  end
+
+  class UsageError < Error
+  end
+
+  class ApiError < Error
+    attr_reader status: Integer?
+    attr_reader body: untyped
+    attr_reader headers: Hash[String, untyped]
+  end
+end

metadata

@@ -0,0 +1,157 @@
+--- !ruby/object:Gem::Specification
+name: smily_cli
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Karol Galanciak
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bookingsync-api
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  smily is an ergonomic, comprehensive command-line client for the BookingSync
+  (Smily) API v3. It offers per-resource commands (list/get/create/update/delete)
+  for the documented endpoints, a raw `api` escape hatch for anything else,
+  OAuth token helpers, config profiles, pagination, and table/json/yaml/csv/ndjson
+  output. Built on the official bookingsync-api client.
+email:
+- karol.galanciak@gmail.com
+executables:
+- smily
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/smily
+- lib/smily_cli.rb
+- lib/smily_cli/base_command.rb
+- lib/smily_cli/cli.rb
+- lib/smily_cli/cli_options.rb
+- lib/smily_cli/client.rb
+- lib/smily_cli/color.rb
+- lib/smily_cli/commands/auth_command.rb
+- lib/smily_cli/commands/config_command.rb
+- lib/smily_cli/commands/mcp_command.rb
+- lib/smily_cli/completion.rb
+- lib/smily_cli/config.rb
+- lib/smily_cli/context.rb
+- lib/smily_cli/errors.rb
+- lib/smily_cli/formatters.rb
+- lib/smily_cli/mcp/client.rb
+- lib/smily_cli/oauth.rb
+- lib/smily_cli/query_options.rb
+- lib/smily_cli/redaction.rb
+- lib/smily_cli/registry.rb
+- lib/smily_cli/resource.rb
+- lib/smily_cli/resource_command.rb
+- lib/smily_cli/result.rb
+- lib/smily_cli/version.rb
+- sig/smily_cli.rbs
+homepage: https://github.com/BookingSync/smily_cli
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/BookingSync/smily_cli
+  source_code_uri: https://github.com/BookingSync/smily_cli
+  changelog_uri: https://github.com/BookingSync/smily_cli/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Command-line client for the BookingSync (Smily) API v3
+test_files: []