fizzy-sdk 0.1.0

data/lib/fizzy/config.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Fizzy
+  # Configuration for the Fizzy API client.
+  #
+  # @example Creating config with defaults
+  #   config = Fizzy::Config.new
+  #
+  # @example Creating config with custom values
+  #   config = Fizzy::Config.new(
+  #     base_url: "https://fizzy.do",
+  #     timeout: 60,
+  #     max_retries: 3
+  #   )
+  #
+  # @example Loading config from environment
+  #   config = Fizzy::Config.from_env
+  class Config
+    # @return [String] API base URL
+    attr_accessor :base_url
+
+    # @return [Integer] request timeout in seconds
+    attr_accessor :timeout
+
+    # @return [Integer] maximum retry attempts for GET requests
+    attr_accessor :max_retries
+
+    # @return [Float] initial backoff delay in seconds
+    attr_accessor :base_delay
+
+    # @return [Float] maximum jitter to add to delays in seconds
+    attr_accessor :max_jitter
+
+    # @return [Integer] maximum pages to fetch in paginated requests
+    attr_accessor :max_pages
+
+    # Default values
+    DEFAULT_BASE_URL = "https://fizzy.do"
+    DEFAULT_TIMEOUT = 30
+    DEFAULT_MAX_RETRIES = 3
+    DEFAULT_BASE_DELAY = 1.0
+    DEFAULT_MAX_JITTER = 0.1
+    DEFAULT_MAX_PAGES = 10_000
+
+    # Creates a new configuration with the given options.
+    #
+    # @param base_url [String] API base URL
+    # @param timeout [Integer] request timeout in seconds
+    # @param max_retries [Integer] maximum retry attempts
+    # @param base_delay [Float] initial backoff delay
+    # @param max_jitter [Float] maximum jitter
+    # @param max_pages [Integer] maximum pages to fetch
+    def initialize(
+      base_url: DEFAULT_BASE_URL,
+      timeout: DEFAULT_TIMEOUT,
+      max_retries: DEFAULT_MAX_RETRIES,
+      base_delay: DEFAULT_BASE_DELAY,
+      max_jitter: DEFAULT_MAX_JITTER,
+      max_pages: DEFAULT_MAX_PAGES
+    )
+      @base_url = normalize_url(base_url)
+      @timeout = timeout
+      @max_retries = max_retries
+      @base_delay = base_delay
+      @max_jitter = max_jitter
+      @max_pages = max_pages
+
+      unless @base_url == normalize_url(DEFAULT_BASE_URL) || localhost?(@base_url)
+        Fizzy::Security.require_https!(@base_url, "base URL")
+      end
+      validate!
+    end
+
+    # Creates a Config from environment variables.
+    #
+    # Environment variables:
+    # - FIZZY_BASE_URL: API base URL
+    # - FIZZY_TIMEOUT: Request timeout in seconds
+    # - FIZZY_MAX_RETRIES: Maximum retry attempts
+    #
+    # @return [Config]
+    def self.from_env
+      new(
+        base_url: ENV.fetch("FIZZY_BASE_URL", DEFAULT_BASE_URL),
+        timeout: ENV.fetch("FIZZY_TIMEOUT", DEFAULT_TIMEOUT).to_i,
+        max_retries: ENV.fetch("FIZZY_MAX_RETRIES", DEFAULT_MAX_RETRIES).to_i
+      )
+    end
+
+    # Loads configuration from a JSON file, with environment overrides.
+    #
+    # @param path [String] path to JSON config file
+    # @return [Config]
+    def self.from_file(path)
+      data = JSON.parse(File.read(path))
+      config = new(
+        base_url: data["base_url"] || DEFAULT_BASE_URL,
+        timeout: data["timeout"] || DEFAULT_TIMEOUT,
+        max_retries: data["max_retries"] || DEFAULT_MAX_RETRIES
+      )
+      config.load_from_env
+      config
+    rescue Errno::ENOENT
+      from_env
+    end
+
+    # Loads environment variable overrides into this config.
+    # @return [self]
+    def load_from_env
+      @base_url = normalize_url(ENV["FIZZY_BASE_URL"]) if ENV["FIZZY_BASE_URL"]
+      @timeout = ENV["FIZZY_TIMEOUT"].to_i if ENV["FIZZY_TIMEOUT"]
+      @max_retries = ENV["FIZZY_MAX_RETRIES"].to_i if ENV["FIZZY_MAX_RETRIES"]
+      Fizzy::Security.require_https!(@base_url, "base URL") unless localhost?(@base_url)
+      validate!
+      self
+    end
+
+    # Returns the default global config directory.
+    # @return [String]
+    def self.global_config_dir
+      config_dir = ENV["XDG_CONFIG_HOME"] || File.join(Dir.home, ".config")
+      File.join(config_dir, "fizzy")
+    end
+
+    private
+
+    def validate!
+      raise ArgumentError, "timeout must be positive" unless @timeout.is_a?(Numeric) && @timeout > 0
+      raise ArgumentError, "max_retries must be non-negative" unless @max_retries.is_a?(Integer) && @max_retries >= 0
+      raise ArgumentError, "max_pages must be positive" unless @max_pages.is_a?(Integer) && @max_pages > 0
+    end
+
+    def normalize_url(url)
+      url&.chomp("/")
+    end
+
+    def localhost?(url)
+      Fizzy::Security.localhost?(url)
+    end
+  end
+end

data/lib/fizzy/cookie_auth.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Fizzy
+  # Cookie-based authentication strategy.
+  # Sets the Cookie header with the session token for session-based auth
+  # (mobile/web clients).
+  #
+  # @example
+  #   auth = Fizzy::CookieAuth.new("session_token_value")
+  #   client = Fizzy.client(auth: auth)
+  class CookieAuth
+    include AuthStrategy
+
+    # @param session_token [String] the session token value
+    # @param cookie_name [String] the cookie name (defaults to "session_token")
+    def initialize(session_token, cookie_name: "session_token")
+      raise ArgumentError, "session_token cannot be nil or empty" if session_token.nil? || session_token.empty?
+
+      @session_token = session_token
+      @cookie_name = cookie_name
+    end
+
+    def authenticate(headers)
+      headers["Cookie"] = "#{@cookie_name}=#{@session_token}"
+    end
+  end
+end

data/lib/fizzy/errors.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+require "json"
+
+# Error types and codes for the Fizzy SDK.
+module Fizzy
+  # Error codes for API responses
+  module ErrorCode
+    USAGE = "usage"
+    NOT_FOUND = "not_found"
+    AUTH = "auth_required"
+    FORBIDDEN = "forbidden"
+    RATE_LIMIT = "rate_limit"
+    NETWORK = "network"
+    API = "api_error"
+    AMBIGUOUS = "ambiguous"
+    VALIDATION = "validation"
+  end
+
+  # Exit codes for CLI tools
+  module ExitCode
+    OK = 0
+    USAGE = 1
+    NOT_FOUND = 2
+    AUTH = 3
+    FORBIDDEN = 4
+    RATE_LIMIT = 5
+    NETWORK = 6
+    API = 7
+    AMBIGUOUS = 8
+    VALIDATION = 9
+  end
+
+  # Base error class for all Fizzy SDK errors.
+  # Provides structured error handling with codes, hints, and CLI exit codes.
+  #
+  # @example Catching errors
+  #   begin
+  #     client.boards.list
+  #   rescue Fizzy::Error => e
+  #     puts "#{e.code}: #{e.message}"
+  #     puts "Hint: #{e.hint}" if e.hint
+  #     exit e.exit_code
+  #   end
+  class Error < StandardError
+    # @return [String] error category code
+    attr_reader :code
+
+    # @return [String, nil] user-friendly hint for resolving the error
+    attr_reader :hint
+
+    # @return [Integer, nil] HTTP status code that caused the error
+    attr_reader :http_status
+
+    # @return [Boolean] whether the operation can be retried
+    attr_reader :retryable
+
+    # @return [Integer, nil] seconds to wait before retrying (for rate limits)
+    attr_reader :retry_after
+
+    # @return [String, nil] X-Request-Id from the response
+    attr_reader :request_id
+
+    # @return [Exception, nil] original error that caused this error
+    attr_reader :cause
+
+    # @param code [String] error category code
+    # @param message [String] error message
+    # @param hint [String, nil] user-friendly hint
+    # @param http_status [Integer, nil] HTTP status code
+    # @param retryable [Boolean] whether operation can be retried
+    # @param retry_after [Integer, nil] seconds to wait before retry
+    # @param request_id [String, nil] X-Request-Id from response
+    # @param cause [Exception, nil] underlying cause
+    def initialize(code:, message:, hint: nil, http_status: nil, retryable: false, retry_after: nil, request_id: nil, cause: nil)
+      super(message)
+      @code = code
+      @hint = hint
+      @http_status = http_status
+      @retryable = retryable
+      @retry_after = retry_after
+      @request_id = request_id
+      @cause = cause
+    end
+
+    # Returns the exit code for CLI applications.
+    # @return [Integer]
+    def exit_code
+      self.class.exit_code_for(@code)
+    end
+
+    # Returns whether this error can be retried.
+    # @return [Boolean]
+    def retryable?
+      @retryable
+    end
+
+    # Maps error codes to exit codes.
+    # @param code [String]
+    # @return [Integer]
+    def self.exit_code_for(code)
+      case code
+      when ErrorCode::USAGE then ExitCode::USAGE
+      when ErrorCode::NOT_FOUND then ExitCode::NOT_FOUND
+      when ErrorCode::AUTH then ExitCode::AUTH
+      when ErrorCode::FORBIDDEN then ExitCode::FORBIDDEN
+      when ErrorCode::RATE_LIMIT then ExitCode::RATE_LIMIT
+      when ErrorCode::NETWORK then ExitCode::NETWORK
+      when ErrorCode::API then ExitCode::API
+      when ErrorCode::AMBIGUOUS then ExitCode::AMBIGUOUS
+      when ErrorCode::VALIDATION then ExitCode::VALIDATION
+      else ExitCode::API
+      end
+    end
+  end
+
+  # Raised when there's a usage error (invalid arguments, missing config).
+  class UsageError < Error
+    def initialize(message, hint: nil)
+      super(code: ErrorCode::USAGE, message: message, hint: hint)
+    end
+  end
+
+  # Raised when a resource is not found (404).
+  class NotFoundError < Error
+    def initialize(resource, identifier, hint: nil)
+      super(
+        code: ErrorCode::NOT_FOUND,
+        message: "#{resource} not found: #{identifier}",
+        hint: hint,
+        http_status: 404
+      )
+    end
+  end
+
+  # Raised when authentication fails (401).
+  class AuthError < Error
+    def initialize(message = "Authentication required", hint: nil, cause: nil)
+      super(
+        code: ErrorCode::AUTH,
+        message: message,
+        hint: hint || "Check your access token or session cookie",
+        http_status: 401,
+        cause: cause
+      )
+    end
+  end
+
+  # Raised when access is denied (403).
+  class ForbiddenError < Error
+    def initialize(message = "Access denied", hint: nil)
+      super(
+        code: ErrorCode::FORBIDDEN,
+        message: message,
+        hint: hint || "You do not have permission to access this resource",
+        http_status: 403
+      )
+    end
+  end
+
+  # Raised when rate limited (429).
+  class RateLimitError < Error
+    def initialize(retry_after: nil, cause: nil)
+      hint = retry_after ? "Try again in #{retry_after} seconds" : "Please slow down requests"
+      super(
+        code: ErrorCode::RATE_LIMIT,
+        message: "Rate limit exceeded",
+        hint: hint,
+        http_status: 429,
+        retryable: true,
+        retry_after: retry_after,
+        cause: cause
+      )
+    end
+  end
+
+  # Raised when there's a network error (connection, timeout, DNS).
+  class NetworkError < Error
+    def initialize(message = "Network error", cause: nil)
+      super(
+        code: ErrorCode::NETWORK,
+        message: message,
+        hint: cause&.message || "Check your network connection",
+        retryable: true,
+        cause: cause
+      )
+    end
+  end
+
+  # Raised for generic API errors.
+  class APIError < Error
+    def initialize(message, http_status: nil, hint: nil, retryable: false, cause: nil)
+      super(
+        code: ErrorCode::API,
+        message: message,
+        hint: hint,
+        http_status: http_status,
+        retryable: retryable,
+        cause: cause
+      )
+    end
+
+    # Creates an APIError from an HTTP status code.
+    # @param status [Integer] HTTP status code
+    # @param message [String, nil] optional error message
+    # @return [APIError]
+    def self.from_status(status, message = nil)
+      message ||= "Request failed (HTTP #{status})"
+      retryable = status >= 500 && status < 600
+      new(message, http_status: status, retryable: retryable)
+    end
+  end
+
+  # Raised when a name/identifier matches multiple resources.
+  class AmbiguousError < Error
+    # @return [Array<String>] list of matching resources
+    attr_reader :matches
+
+    def initialize(resource, matches: [])
+      @matches = matches
+      hint = if matches.any? && matches.length <= 5
+               "Did you mean: #{matches.join(", ")}"
+      else
+               "Be more specific"
+      end
+      super(
+        code: ErrorCode::AMBIGUOUS,
+        message: "Ambiguous #{resource}",
+        hint: hint
+      )
+    end
+  end
+
+  # Raised for validation errors (400, 422).
+  class ValidationError < Error
+    def initialize(message, hint: nil, http_status: 400)
+      super(
+        code: ErrorCode::VALIDATION,
+        message: message,
+        hint: hint,
+        http_status: http_status
+      )
+    end
+  end
+
+  # Maps an HTTP response to the appropriate error class.
+  #
+  # @param status [Integer] HTTP status code
+  # @param body [String, nil] response body (will attempt JSON parse)
+  # @param retry_after [Integer, nil] Retry-After header value
+  # @return [Error]
+  def self.error_from_response(status, body = nil, retry_after: nil)
+    message = parse_error_message(body) || "Request failed"
+
+    case status
+    when 400, 422
+      ValidationError.new(message, http_status: status)
+    when 401
+      AuthError.new(message)
+    when 403
+      ForbiddenError.new(message)
+    when 404
+      NotFoundError.new("Resource", "unknown")
+    when 429
+      RateLimitError.new(retry_after: retry_after)
+    when 500
+      APIError.new("Server error (500)", http_status: 500, retryable: true)
+    when 502, 503, 504
+      APIError.new("Gateway error (#{status})", http_status: status, retryable: true)
+    else
+      APIError.from_status(status, message)
+    end
+  end
+
+  # Parses error message from response body.
+  # @param body [String, nil]
+  # @return [String, nil]
+  def self.parse_error_message(body)
+    return nil if body.nil? || body.empty?
+
+    # Guard against oversized error bodies before parsing
+    Fizzy::Security.check_body_size!(body, Fizzy::Security::MAX_ERROR_BODY_BYTES, "Error")
+
+    data = JSON.parse(body)
+    msg = data["error"] || data["message"]
+    msg ? Fizzy::Security.truncate(msg) : nil
+  rescue JSON::ParserError, Fizzy::APIError
+    # Return nil on parse errors or oversized bodies to preserve normal error type mapping
+    nil
+  end
+end