superthread 0.7.2

data/lib/superthread/configuration.rb

@@ -0,0 +1,354 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "yaml"
+
+module Superthread
+  # Manages configuration and state for the Superthread CLI.
+  #
+  # Handles multi-account management, API credentials, and persistent state.
+  # Configuration is stored in XDG-compliant locations:
+  # - Config: ~/.config/superthread/config.yaml (accounts, settings)
+  # - State: ~/.local/state/superthread/context.yaml (current account, workspace)
+  #
+  # Environment variables can override file-based configuration:
+  # - SUPERTHREAD_API_KEY - API key for authentication
+  # - SUPERTHREAD_WORKSPACE_ID - Default workspace ID
+  # - SUPERTHREAD_ACCOUNT - Account name to use
+  # - SUPERTHREAD_API_BASE_URL - Custom API base URL
+  #
+  # @example Basic usage
+  #   config = Superthread::Configuration.new
+  #   config.validate!
+  #   config.api_key  # => "sk_..."
+  class Configuration
+    # Default API base URL for the Superthread API.
+    DEFAULT_BASE_URL = "https://api.superthread.com/v1"
+
+    # @return [String] API base URL
+    attr_accessor :base_url
+
+    # @return [String] Output format for CLI (table, json, etc.)
+    attr_accessor :format
+
+    # @return [Integer] HTTP request timeout in seconds
+    attr_accessor :timeout
+
+    # @return [Integer] HTTP connection timeout in seconds
+    attr_accessor :open_timeout
+
+    # Creates a new Configuration instance.
+    #
+    # Loads configuration from files and environment variables in this order:
+    # 1. Default values
+    # 2. Config file (~/.config/superthread/config.yaml)
+    # 3. State file (~/.local/state/superthread/context.yaml)
+    # 4. Environment variables (highest priority)
+    def initialize
+      @base_url = DEFAULT_BASE_URL
+      @format = "table"
+      @timeout = 30
+      @open_timeout = 10
+      @config_data = {}
+      @state_data = {}
+
+      load_config_file
+      load_state_file
+      load_env_vars
+    end
+
+    # Returns the path to the configuration file.
+    #
+    # Uses XDG_CONFIG_HOME if set, otherwise defaults to ~/.config.
+    #
+    # @return [String] absolute path to config.yaml
+    def config_path
+      @config_path ||= File.join(
+        ENV.fetch("XDG_CONFIG_HOME", File.expand_path("~/.config")),
+        "superthread",
+        "config.yaml"
+      )
+    end
+
+    # Returns the path to the state file.
+    #
+    # Uses XDG_STATE_HOME if set, otherwise defaults to ~/.local/state.
+    # State includes ephemeral data like current account and workspace.
+    #
+    # @return [String] absolute path to context.yaml
+    def state_path
+      @state_path ||= File.join(
+        ENV.fetch("XDG_STATE_HOME", File.expand_path("~/.local/state")),
+        "superthread",
+        "context.yaml"
+      )
+    end
+
+    # Returns all configured accounts from the config file.
+    #
+    # @return [Hash{Symbol => Hash}] account names mapped to their settings
+    def accounts
+      @config_data[:accounts] || {}
+    end
+
+    # Returns the current account name.
+    #
+    # Checks environment variable first, then falls back to state file.
+    #
+    # @return [String, nil] current account name or nil if not set
+    def current_account
+      @env_account || @state_data[:current_account]
+    end
+
+    # Switches to a different account.
+    #
+    # Updates the state file with the new current account.
+    #
+    # @param name [String] account name to switch to
+    # @raise [ConfigurationError] if the account does not exist
+    def current_account=(name)
+      name = name.to_s
+      raise ConfigurationError, "Account '#{name}' not found" unless accounts.key?(name.to_sym)
+
+      @state_data[:current_account] = name
+      save_state_file
+    end
+
+    # Returns ephemeral state for an account.
+    #
+    # State includes workspace_id and workspace_name.
+    #
+    # @param name [String, nil] account name (defaults to current account)
+    # @return [Hash, nil] account state hash or nil if not found
+    def account_state(name = current_account)
+      return nil unless name
+
+      state_accounts = @state_data[:accounts] || {}
+      state_accounts[name.to_sym] || {}
+    end
+
+    # Adds a new account to the configuration.
+    #
+    # @param name [String] unique account name
+    # @param api_key [String] API key for authentication
+    def add_account(name, api_key:)
+      name = name.to_s
+      @config_data[:accounts] ||= {}
+      @config_data[:accounts][name.to_sym] = {api_key: api_key}
+      save_config_file
+    end
+
+    # Removes an account from config and state.
+    #
+    # If removing the current account, clears the current account selection.
+    #
+    # @param name [String] account name to remove
+    def remove_account(name)
+      name = name.to_s
+      @config_data[:accounts]&.delete(name.to_sym)
+      @state_data[:accounts]&.delete(name.to_sym)
+
+      # If removing current account, clear it
+      if @state_data[:current_account] == name
+        @state_data.delete(:current_account)
+      end
+
+      save_config_file
+      save_state_file
+    end
+
+    # Saves ephemeral state for an account.
+    #
+    # Used to persist workspace selection between sessions.
+    #
+    # @param name [String] the configured account alias (e.g., "work", "personal")
+    # @param workspace_id [String] workspace ID to save
+    # @param workspace_name [String, nil] optional workspace name for display
+    def save_account_state(name, workspace_id:, workspace_name: nil)
+      name = name.to_s
+      @state_data[:accounts] ||= {}
+      @state_data[:accounts][name.to_sym] = {
+        workspace_id: workspace_id,
+        workspace_name: workspace_name
+      }.compact
+      save_state_file
+    end
+
+    # Sets the current account in state.
+    #
+    # Unlike the setter, this does not validate the account exists.
+    #
+    # @param name [String] the configured account alias to make current
+    def set_current_account(name)
+      @state_data[:current_account] = name.to_s
+      save_state_file
+    end
+
+    # Returns the API key for the current context.
+    #
+    # Checks in order: manual override, environment variable, account config.
+    #
+    # @return [String, nil] API key or nil if not configured
+    def api_key
+      return @manual_api_key if @manual_api_key
+      return @env_api_key if @env_api_key
+
+      account = accounts[current_account&.to_sym]
+      account&.dig(:api_key)
+    end
+
+    # Sets a manual API key override.
+    #
+    # Useful for testing or scripting without modifying config files.
+    #
+    # @param key [String] Superthread API key for authentication
+    def api_key=(key)
+      @manual_api_key = key
+    end
+
+    # Sets a manual workspace ID override.
+    #
+    # Useful for programmatic usage without modifying config files.
+    #
+    # @param id [String] workspace ID
+    def workspace=(id)
+      @manual_workspace = id
+    end
+
+    # Returns the workspace ID for the current context.
+    #
+    # Checks in order: manual override, environment variable, account state.
+    #
+    # @return [String, nil] workspace ID or nil if not set
+    def workspace
+      return @manual_workspace if @manual_workspace
+      return @env_workspace if @env_workspace
+
+      account_state&.dig(:workspace_id)
+    end
+
+    # Returns the workspace name for display purposes.
+    #
+    # @return [String, nil] workspace name or nil if not set
+    def workspace_name
+      account_state&.dig(:workspace_name)
+    end
+
+    # Validates that required configuration is present.
+    #
+    # @return [void]
+    # @raise [ConfigurationError] if no account is configured
+    # @raise [ConfigurationError] if API key is missing
+    def validate!
+      # Allow manual or env API key to bypass account requirement
+      return if @manual_api_key && !@manual_api_key.empty?
+      return if @env_api_key && !@env_api_key.empty?
+
+      unless current_account
+        raise ConfigurationError,
+          "No account configured. Run 'suth setup' to configure an account."
+      end
+
+      unless api_key && !api_key.empty?
+        raise ConfigurationError,
+          "API key not found for account '#{current_account}'. " \
+          "Run 'suth setup' or set SUPERTHREAD_API_KEY environment variable."
+      end
+    end
+
+    # Checks if any accounts are configured.
+    #
+    # @return [Boolean] true if at least one account exists
+    def accounts?
+      accounts.any?
+    end
+
+    # Persists the current configuration to the config file.
+    #
+    # Creates parent directories if they don't exist.
+    #
+    # @return [void]
+    def save_config_file
+      FileUtils.mkdir_p(File.dirname(config_path))
+      data = {
+        "accounts" => stringify_keys(accounts),
+        "format" => @format,
+        "timeout" => @timeout,
+        "open_timeout" => @open_timeout
+      }
+      data["base_url"] = @base_url if @base_url != DEFAULT_BASE_URL
+      File.write(config_path, YAML.dump(data))
+    end
+
+    # Persists the current state to the state file.
+    #
+    # Creates parent directories if they don't exist.
+    #
+    # @return [void]
+    def save_state_file
+      FileUtils.mkdir_p(File.dirname(state_path))
+      data = {}
+      data["current_account"] = @state_data[:current_account] if @state_data[:current_account]
+      if @state_data[:accounts]&.any?
+        data["accounts"] = stringify_keys(@state_data[:accounts])
+      end
+      File.write(state_path, YAML.dump(data))
+    end
+
+    private
+
+    # Loads configuration from the config file.
+    #
+    # @return [void]
+    def load_config_file
+      return unless File.exist?(config_path)
+
+      config = YAML.safe_load_file(config_path, symbolize_names: true)
+      return unless config.is_a?(Hash)
+
+      @config_data = config
+      @base_url = config[:base_url] if config[:base_url]
+      @format = config[:format] if config[:format]
+      @timeout = config[:timeout] if config[:timeout]
+      @open_timeout = config[:open_timeout] if config[:open_timeout]
+    rescue Psych::SyntaxError => e
+      raise ConfigurationError, "Invalid YAML in #{config_path}: #{e.message}"
+    end
+
+    # Loads state from the state file.
+    #
+    # @return [void]
+    def load_state_file
+      return unless File.exist?(state_path)
+
+      state = YAML.safe_load_file(state_path, symbolize_names: true)
+      return unless state.is_a?(Hash)
+
+      @state_data = state
+    rescue Psych::SyntaxError => e
+      raise ConfigurationError, "Invalid YAML in #{state_path}: #{e.message}"
+    end
+
+    # Loads configuration overrides from environment variables.
+    #
+    # @return [void]
+    def load_env_vars
+      @env_api_key = ENV["SUPERTHREAD_API_KEY"] if ENV["SUPERTHREAD_API_KEY"]
+      @env_workspace = ENV["SUPERTHREAD_WORKSPACE_ID"] if ENV["SUPERTHREAD_WORKSPACE_ID"]
+      @env_account = ENV["SUPERTHREAD_ACCOUNT"] if ENV["SUPERTHREAD_ACCOUNT"]
+      @base_url = ENV["SUPERTHREAD_API_BASE_URL"] if ENV["SUPERTHREAD_API_BASE_URL"]
+    end
+
+    # Converts symbol keys to strings for YAML output.
+    #
+    # @param hash [Hash, nil] the hash to convert
+    # @return [Hash] the hash with string keys
+    def stringify_keys(hash)
+      return {} unless hash
+
+      hash.transform_keys(&:to_s).transform_values do |v|
+        v.is_a?(Hash) ? stringify_keys(v) : v
+      end
+    end
+  end
+end

data/lib/superthread/connection.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module Superthread
+  # Low-level HTTP connection wrapper using Faraday.
+  #
+  # Handles the actual HTTP communication with the Superthread API,
+  # including authentication headers, timeouts, and JSON encoding.
+  #
+  # @api private
+  class Connection
+    # Creates a new connection with the given configuration.
+    #
+    # @param config [Superthread::Configuration] configuration with API credentials
+    def initialize(config)
+      @config = config
+      @connection = build_connection
+    end
+
+    # Performs an HTTP request to the API.
+    #
+    # @param method [Symbol] HTTP method (:get, :post, :patch, :delete)
+    # @param path [String] API endpoint path (leading slash is stripped)
+    # @param params [Hash{Symbol => Object}, nil] query parameters
+    # @param body [Hash{Symbol => Object}, nil] request body (will be JSON-encoded)
+    # @return [Faraday::Response] raw HTTP response
+    def request(method:, path:, params: nil, body: nil)
+      # Remove leading slash - Faraday treats /path as absolute from host root,
+      # but we want it relative to the base URL (which includes /v1)
+      relative_path = path.sub(%r{^/}, "")
+
+      @connection.send(method) do |req|
+        req.url(relative_path)
+        req.params = params if params
+        req.body = body.to_json if body
+      end
+    end
+
+    private
+
+    # Builds a configured Faraday connection for API requests.
+    #
+    # @return [Faraday::Connection] connection with auth headers and timeouts
+    def build_connection
+      Faraday.new(url: @config.base_url) do |conn|
+        conn.headers["Authorization"] = "Bearer #{@config.api_key}"
+        conn.headers["Content-Type"] = "application/json"
+        conn.headers["Accept"] = "application/json"
+        conn.options.timeout = @config.timeout
+        conn.options.open_timeout = @config.open_timeout
+        conn.adapter Faraday.default_adapter
+      end
+    end
+  end
+end

data/lib/superthread/error.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module Superthread
+  # Base class for API errors from HTTP responses.
+  #
+  # Contains detailed information about the failed request including
+  # status code, response body, and the original Faraday response.
+  #
+  # @example Handling API errors
+  #   begin
+  #     client.cards.find(workspace_id, card_id)
+  #   rescue Superthread::NotFoundError => e
+  #     puts "Card not found: #{e.message}"
+  #   rescue Superthread::ApiError => e
+  #     puts "API error (#{e.status}): #{e.message}"
+  #   end
+  class ApiError < Error
+    # @return [Integer, nil] HTTP status code
+    attr_reader :status
+
+    # @return [Hash{Symbol => Object}, String, nil] parsed response body
+    attr_reader :body
+
+    # @return [Faraday::Response, nil] original HTTP response
+    attr_reader :response
+
+    # Creates an ApiError from HTTP response data.
+    #
+    # @param message [String] human-readable error message
+    # @param status [Integer, nil] HTTP status code
+    # @param body [String, Hash{Symbol => Object}, nil] response body
+    # @param response [Faraday::Response, nil] original response object
+    def initialize(message, status: nil, body: nil, response: nil)
+      @status = status
+      @body = body
+      @response = response
+      super(build_message(message))
+    end
+
+    # Creates the appropriate error type from an HTTP response.
+    #
+    # Examines both status code and body content to determine the best error class.
+    #
+    # @param response [Faraday::Response] the HTTP response
+    # @return [Superthread::ApiError] the appropriate error subclass
+    def self.from_response(response)
+      status = response.status
+      body = parse_body(response.body)
+      message = extract_message(body)
+
+      klass = error_class_for(status, body)
+      klass.new(message, status: status, body: body, response: response)
+    end
+
+    # Determines the appropriate error class based on status and body.
+    #
+    # @param status [Integer] HTTP status code
+    # @param body [Hash{Symbol => Object}, String] response body
+    # @return [Class] error class to use
+    def self.error_class_for(status, body)
+      case status
+      when 400 then ValidationError
+      when 401 then AuthenticationError
+      when 403 then error_for_403(body)
+      when 404 then NotFoundError
+      when 422 then ValidationError
+      when 429 then RateLimitError
+      when 400..499 then ClientError
+      when 500..599 then ServerError
+      else ApiError
+      end
+    end
+
+    # Determines the specific error class for 403 responses.
+    #
+    # 403 errors may indicate rate limiting or permission issues depending on the body.
+    #
+    # @param body [Hash{Symbol => Object}, String] response body
+    # @return [Class] specific error class
+    def self.error_for_403(body)
+      message = body.is_a?(Hash) ? body[:message].to_s : body.to_s
+
+      case message.downcase
+      when /rate limit/i then RateLimitError
+      when /permission/i, /access denied/i then ForbiddenError
+      else ForbiddenError
+      end
+    end
+
+    # Parses the response body into a hash if possible.
+    #
+    # @param body [String, nil] raw response body
+    # @return [Hash{Symbol => Object}, String] parsed body or original string
+    def self.parse_body(body)
+      return {} if body.nil? || body.empty?
+
+      JSON.parse(body, symbolize_names: true)
+    rescue JSON::ParserError
+      body.to_s
+    end
+
+    # Extracts an error message from the response body.
+    #
+    # @param body [Hash{Symbol => Object}, String] response body
+    # @return [String] error message
+    def self.extract_message(body)
+      case body
+      when Hash
+        body[:message] || body[:error] || body[:error_description] || "Unknown error"
+      else
+        body.to_s.empty? ? "Unknown error" : body.to_s
+      end
+    end
+
+    private
+
+    # Builds a formatted error message with HTTP status prefix.
+    #
+    # @param message [String] the error message text
+    # @return [String] formatted message with status code if present
+    def build_message(message)
+      parts = []
+      parts << "HTTP #{@status}" if @status
+      parts << message
+      parts.join(": ")
+    end
+  end
+
+  # HTTP 4xx - Client errors (base class)
+  class ClientError < ApiError; end
+
+  # HTTP 5xx - Server errors
+  class ServerError < ApiError; end
+
+  # HTTP 401 - Invalid API key or authentication required
+  class AuthenticationError < ClientError; end
+
+  # HTTP 403 - Permission denied or forbidden action
+  class ForbiddenError < ClientError; end
+
+  # HTTP 404 - Resource not found
+  class NotFoundError < ClientError; end
+
+  # HTTP 400/422 - Validation error or invalid request
+  class ValidationError < ClientError; end
+
+  # Raised when the API rate limit is exceeded (HTTP 429).
+  class RateLimitError < ClientError
+    # Returns the number of seconds to wait before retrying.
+    #
+    # @return [Integer, nil] seconds to wait, or nil if not available
+    def retry_after
+      return nil unless @response
+
+      @response.headers["retry-after"]&.to_i
+    end
+  end
+
+  # Raised when path or ID validation fails on the client side.
+  #
+  # This error is raised before making an API request when the provided
+  # path or ID is invalid (e.g., contains invalid characters).
+  class PathValidationError < Error; end
+end

data/lib/superthread/mention_formatter.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Superthread
+  # Converts {{@mentions}} in content to Superthread's HTML user-mention tags.
+  #
+  # Superthread allows user names with spaces, punctuation, and titles
+  # (e.g., "John A. J. Smith the 3rd, Esq."), making traditional @mention
+  # syntax unreliable. The {{@Name}} template syntax provides unambiguous
+  # delimiters that handle any valid display name.
+  #
+  # Uses a three-pass algorithm:
+  # 1. Escape protected mentions: `\{{@Name}}` -> placeholder
+  # 2. Replace mentions: `{{@Name}}` -> `<user-mention>` HTML tag
+  # 3. Restore escaped text: placeholder -> `{{@Name}}`
+  #
+  # @example Basic usage
+  #   formatter = MentionFormatter.new(client, "ws-123")
+  #   formatter.format("Hey {{@Steve Clarke}}, check this")
+  #   # => 'Hey <user-mention data-type="mention" user-id="u123" ...></user-mention>, check this'
+  #
+  # @example Escaping
+  #   formatter.format('Use \{{@Username}} syntax to mention users')
+  #   # => "Use {{@Username}} syntax to mention users"
+  class MentionFormatter
+    # @return [Regexp] pattern matching `{{@Name}}` mention templates
+    MENTION_PATTERN = /\{\{@([^}]+)\}\}/
+    # @return [Regexp] pattern matching escaped `\{{@Name}}` mentions
+    ESCAPE_PATTERN = /\\\{\{@([^}]+)\}\}/
+    # @return [Regexp] pattern matching placeholders used during escape processing
+    PLACEHOLDER_PATTERN = /___ESCAPED_MENTION_(.+?)___END___/
+
+    # @param client [Superthread::Client] the API client for fetching members
+    # @param workspace_id [String] the workspace to look up members in
+    def initialize(client, workspace_id)
+      @client = client
+      @workspace_id = workspace_id
+    end
+
+    # Formats mention templates in content to HTML user-mention tags.
+    #
+    # @param content [String, nil] text that may contain {{@Name}} patterns
+    # @return [String, nil] content with mentions converted to HTML tags
+    def format(content)
+      return content if content.nil? || !content.include?("{{@")
+
+      member_map = build_member_map
+      return content if member_map.nil?
+
+      mention_time = Time.now.to_i
+
+      # Pass 1: protect escaped mentions (store name only, not the {{@ }} delimiters)
+      result = content.gsub(ESCAPE_PATTERN, '___ESCAPED_MENTION_\1___END___')
+
+      # Pass 2: replace {{@Name}} with HTML tags
+      result = result.gsub(MENTION_PATTERN) do |match|
+        name = Regexp.last_match(1).strip
+        member = member_map[name.downcase]
+
+        if member
+          safe_id = CGI.escapeHTML(member[:id])
+          safe_name = CGI.escapeHTML(member[:name])
+          '<user-mention data-type="mention" ' \
+            "user-id=\"#{safe_id}\" " \
+            "mention-time=\"#{mention_time}\" " \
+            "user-value=\"#{safe_name}\" " \
+            'denotation-char="@"></user-mention>'
+        else
+          match
+        end
+      end
+
+      # Pass 3: restore escaped mentions as literal {{@Name}} text
+      result.gsub(PLACEHOLDER_PATTERN, '{{@\1}}')
+    end
+
+    private
+
+    # Fetches workspace members and builds a case-insensitive lookup map.
+    #
+    # @return [Hash{String => Hash}, nil] map of lowercase names to {id:, name:}, or nil on failure
+    def build_member_map
+      @client.users.members(@workspace_id).each_with_object({}) do |member, map|
+        next unless member.display_name
+
+        map[member.display_name.downcase] = {
+          id: member.user_identifier,
+          name: member.display_name
+        }
+      end
+    rescue Superthread::Error
+      nil
+    end
+  end
+end